New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Wishlist: Documentation #41

Open
jankeromnes opened this Issue Mar 2, 2017 · 2 comments

Comments

Projects
None yet
1 participant
@jankeromnes
Copy link
Member

jankeromnes commented Mar 2, 2017

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 (#31) which should make hacking Janitor much simpler
  • Centralize all documentation links directly in README.md
  • 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 (#26) which is great for writing documentation where it's needed the most
  • Show the SelfAPI automated documentation (#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

This comment has been minimized.

Copy link
Member

jankeromnes commented Mar 10, 2017

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

This comment has been minimized.

Copy link
Member

jankeromnes commented Jul 9, 2017

  • Showcase cool features with screenshots and GIFs a bit like the JetBrains IDE websites.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment