Software Development/Project Documentation

From The Thinkulum
Jump to navigation Jump to search

READMEs give the reader a basic intro to your project, but at some point they'll need more extensive information. I'm calling this in-depth treatment the project documentation.

Documentation generation

Some documentation is freeform writing, but using documentation generators a lot of it can be collected from specialized comments and formatted automatically. You'd mainly use this to document your API. Sphinx is a popular Python tool for this purpose. It handles both types of documentation.

My default Sphinx setup will be in my cookiecutter templates.

Content

I didn't find many guides to writing user or developer guides beyond the README, so I may have to write my own at some point, based on an examination of well-documented projects. But here's one guide that covers some of the information developers will need:

One source of insight for documenters might be the content of man pages. Man (manual) pages are the documentation for Unix tools, and they have a fairly standard format.