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:

Other resources

Worst-case scenario

Avoid the following scenario as much as possible. This is taken from “Lecture 12: FOSS Culture” of the ANU course COMP8440:

From: xxxxx
Date: Fri, 9 Feb 2001 21:07:09 +0900
To: rusty@rustcorp.com.au
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)

Advertisements
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: