Document your software
This is a follow-up to my post Sage Documentation Quality Initiative. In this post, I collect together some resources on writing documentation for a software project. The information in this post is also available on the Sage wiki page Sage Documentation Project.
Writing great documentation
Jacob Kaplan-Moss has written a series of three articles on how to write great documentation for any open source project. Here is a list of his articles:
- What to write — Various types of documents that a project should have, including reference manual, tutorials, brief feature tours, development guidelines, etc.
- Technical style — good technical styles to follow.
- You need an editor — on the importance of having an editor to look after the project’s documentation.
Darrell Anderson has some tips on technical writing that are well worth a read:
- Bigshot Words — some words to avoid. Dilbert also has some tips.
- A Proofreader’s Checklist — common grammatical and spelling mistakes to look out for.
- Technical Writing Tips — numerous points to keep in mind in technical writing.
- It also helps to use a spell checker.
- Documentation issues in open source from OSS Watch.
- How to Write Documentation that Will Lead to New Users by Jack Herrington.
- Open-source documentation: in search of user-driven, just-in-time writing by Erik Berglund and Michael Priestley. In “SIGDOC ’01: Proceedings of the 19th Annual International Conference on Computer Documentation”, ACM, pages 132–141, 2001.
- S Van der Walt. The SciPy Documentation Project (Technical Overview). In Proceedings of the 7th Python in Science conference (SciPy 2008), G Varoquaux, T Vaught, J Millman (Eds.), pp.27–28.
- J Harrington. The SciPy Documentation Project. In Proceedings of the 7th Python in Science conference (SciPy 2008), G Varoquaux, T Vaught, J Millman (Eds.), pp.33–35.
- J Harrington, D Goldsmith. Progress Report: NumPy and SciPy Documentation in 2009. In Proceedings of the 8th Python in Science conference (SciPy 2009), G Varoquaux, S van der Walt, J Millman (Eds.), pp.84–87.
- Documentation by [insert doc type] covers what isn’t documentation.
Avoid the following scenario as much as possible. This is taken from “Lecture 12: FOSS Culture” of the ANU course COMP8440:
Date: Fri, 9 Feb 2001 21:07:09 +0900
Subject: Dear Sir,
I have always wanted to flame you, however I never really had any good reason to do so. While your software creations were always egoistical and underdocumented, nothing really pushed the mark, yet. Until today, when I downloaded your “Linux 2.4” call graph utility. So, when is your next absolute-next-to-worthless but oh-so-cool-because-it’s-from-rusty-russell piece of software coming out? Why the f*** don’t you focus on documenting things instead of writing useless shit that “takes about 8 hours to run on my mobile pII laptop” or “generates about 180mb of vector postscript”. How about another example. I heard you were involved with that atrocity called “netfilter”. Sure, it might have nice features and I am still considering using it, but WRITE SOME F***ING DOCS before you release complex shit like this for people to use! When I goto that netfilter site, I don’t give a flying raging f*** who submitted 31337 lines of code to whatever f***ing netfilter module. That’s your egoistical shit, and I could care less about it.
…… (more rants delted)
… Uhm, that’s all I can think of right now.
xxx (name deleted)