How to write good documentation quickly


As you know we launched the Panton Principles 2 months ago.  There has been a lot of interest and I have been talking with a number of open access and open data publishers to convince them of the value of making their data explicitly open.  I described the principles in words but realized that they needed something more substantial to read which is tailored to their particular needs.  So I decided to write an FAQ.

This can be a very tedious process but I enlisted the help of the open knowledge foundation.  We decided that I would ask the questions and that we would communally answer them.  I wrote a series of questions

And then we set up a pirate pad.  This is a communal open website where any one can edit a document.  It’s rather like google docs but is better for simultaneous editing and requires less problems in inviting people.

About six or seven people actively participated and within a day we had the bulk of the FAQ written.  This is because different people were able to answer different questions because they brought different experience and ideas.  If I had had to do the whole thing myself I would probably still be scratching away at some of the questions and answers.

You can see the answers at .

Joe and I have decided to create an FAQ for Chem4Word.  I have suggested about 20 questions along the lines of the FAQ above – and together we will answer them.  In fact given the relative ease of speaking to the machine I will find it quite pleasant to dictate some of the answers on this blog.  This means that not only can they be incorporated in the FAQ but that there will be a public exposure of some of the issues.

This entry was posted in Uncategorized. Bookmark the permalink.

One Response to How to write good documentation quickly

  1. Pingback: Twitter Trackbacks for Unilever Centre for Molecular Informatics, Cambridge - How to write good documentation quickly « petermr’s blog [] on

Leave a Reply

Your email address will not be published. Required fields are marked *