Wishlist: Documentation

[jankeromnes]

I asked @JeremiePat about a good documentation strategy for Janitor, and he sent me this fantastic email:

When documenting a product the question you should ask yourself is: Who will need that documentation and for what purpose?
Regarding your project, I can identified two type of people: Developers who want to use Janitor and developers who want to hack it.

For those who want to use it, I think you already have a good starting point with the Janitor Web site and the readme file in the github repository. In that area my suggestion would be to:

• enhance the readme file and mirror it on the Janitor web site.
• add a FAQ on both the web site and github to answer common install troubleshooting issues.
• create tutorials to demonstrate each individual user facing feature of Janitor, and make them available on the web site.

For those who want to hack it, it is a little bit more complicated as it is necessary to provide different information at different level:

• Providing a high level architecture document will help new comers to get use to the organization of the code base
• Provide building and testing documentation (with solution to well known issues)
• Also providing a document with the "rules" to follow for contributing (code standard, test policy, review process, etc.) This can safely live on the github wiki or on wikimo as you wish. Such documentation is usually quite fluid as it changes along the life of the project so a Wiki is a good place for that.
• For people who will hack the code, I always recommend to document as close as possible from the source code to avoid having people looking everywhere for information (it's time consuming and inefficient). However, if, for example you have a good documentation inline with the code, I always suggest to use tools (like Sphinx, Doxygen, JSDoc, etc.) to extract and build a more human friendly documentation. Such documentation can be host on the Janitor web site. The big advantage is that by using such tools in addition to a review requirement for inline documentation you'll get up to date documentation at a low cost.

This is a start, I suggest to prioritize the documentation work by asking new comers what information they are missing. This will give you a good hint of what is important in the short term. I also suggest to make documentation part of the acceptance criteria for pull request, that way you'll reduce the documentation debt (only legacy stuff will require some effort) and you'll start create a culture of documentation for the future which will make things easier along the way.

Additionally, I think we should:

• Add Janitor to Janitor (Put The Janitor in The Janitor #31) which should make hacking Janitor much simpler
• Centralize all documentation links directly in README.md
• Add an "about" page (Add an "about" page #5) with a high-level overview of how the Janitor works; what's required to use it; and maybe what we're trying to achieve with it
• Create a Discourse (Add a Discourse for the Janitor community, with solutions to common issues #26) which is great for writing documentation where it's needed the most
• Show the SelfAPI automated documentation (Add an automatically generated API reference page to the website. #66) for the /api/* folder directly on the website (e.g. at https://janitor.technology/reference/api/)

If you have another idea that could improve Janitor's documentation, please comment below. Thanks!

[jankeromnes]

I think that the TaskCluster tutorial is clear and simple, and it's amazing that it guides you to the most relevant information for what you wish to do. I'd love us to have a similar tutorial.

Edit: A great and simple way to continuously improve the questions at the bottom would be to have a "Missing question?" input field just below with a "Suggest" button (that says "Thank you" when you suggest a new question).

Edit 2: Phabricator's docs (generated by their "Diviner" tool) also have Next Steps / "Continue by" links at the bottom of pages, and they would also benefit from a "Missing link?" suggestion box.

[jankeromnes]

• Showcase cool features with screenshots and GIFs a bit like the JetBrains IDE websites.