Level Up 7: Creates and maintains useful documentation for projects

gistfile1.txt

1. What is a useful level of documentation?

Documentation should cover the following items: 

- How to install the software and any dependencies, such as Ruby version.
- How to use the API and public methods.
- The current way of doing things and the proper idioms to use.
- Including meaningful examples of how to use the software.
- How to upgrade if moving up versions.

2. How much documentation is enough? How much is too much? How can we balance those needs?

There should be enough documentation where the average user can install the software, use the software as a whole, and also get detailed usage of public-facing API methods. Rails is a good example. It has a number of Guides that breaks down the components of the software, demonstrates how to use them and points out edge cases or caveats. It also has detailed documentation for every method available to the public. 

In my opinion, too much documentation would include unnecessary descriptions of the internal workings of the software. The people this is relevant to likely know the code very well; if not, reading the source itself is probably the best way to understand the software at this level of detail. In general, it is best to err on the side of too much documentation, but this must be balanced with ensuring it is accurate. If there is too much documentation, it is harder to keep it up to date. In addition, providing good examples of using the software should be a higher priority than providing extremely detailed documentation on little-known methods. It is most important to get users up and running in using the software.

3. Add some useful documentation to your existing code.

I added useful documentation for using my Dinodex, Data Science, Overlord and Rails projects.