Writing documentation for RIP.

[bIgBV]

I am raising this issue as a platform to discuss the following topics:

• How to document RIP ?
• Which tool to use.
• Using document generators ?
• Or do we write external documentation.
• Marking parts are considerably stable so that we can start documenting them.

If you have any other point to raise, please do so.

[bIgBV]

I feel using documentation generators such as Sphinx with documentation guidelines would be a good idea. With a standard documentation guideline we can generate documentation for different versions.

This also moves the responsibility of writing the documentation on to the developer who will have the most context about the given feature being added in a PR.

Having a documentation checks in the PR process would help ensure that at least, new features being added will be properly documented.

[robinmaben]

@bIgBV Can we use ReadTheDocs? They support both Mkdocs and Sphinx among many others. They directly pull from your repo and generate a site that can be hosted at a subdomain. All this, free of cost for open source projects.

https://docs.readthedocs.org/en/latest/features.html

[uttamk]

+1 to both @bIgBV and @robinmaben.
Read the docs seem to have an automatic way of updating the documentation which can be done as a part of the build from travis
Totally agree on the point of enforcing documentation in peer reviews

[bIgBV]

@uttamk we should update the contributing guidelines with the documentation style which we want to enforce. Also, @robinmaben that answers the question I had about where this documentation would be hosted.

[bIgBV]

I know that sphinx supports documentation for different versions, but I am not completely certain about how we'll structure the different versions. Will any enhancements being added to RIP henceforth be a different version and we can start documenting existing features ?

[uttamk]

I suppose we will have a minor version for each milestone (that doesn't
break the api). Older documentation is not a big problem for these
releases. It will however matter when we do a major release when there will
be breaking api changes.

On Tue, Jan 19, 2016 at 12:24 PM, Bhargav notifications@github.com wrote:

I know that sphinx supports documentation for different versions, but I am
not completely certain about how we'll structure the different versions.
Will any enhancements being added to RIP henceforth be a different version
and we can start documenting existing features ?

—
Reply to this email directly or view it on GitHub
#34 (comment).