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

• Basics
• Q1: What are the Panton Principles?
• Q2: Why the Panton Principles?
• Q3: Why are the Panton Principles important?
• Q4: Who has adopted the Panton Principles?
• Q5: Who are the Open Knowledge Foundation and Science Commons?
• Q6: Are the Panton Principles sponsored, supported, or considered in any way by the Open Source Initiative, the Free Software Foundation, the Electronic Frontier Foundation or other organizations? (i.e., what are their contributed opinions?)
• Q7: Is “Open Data” a precise term?
• Q8: Is Open Data the same as Open Source or Open Access?
• Q9: Is Open Data the same as CC0 or PDDL?
• Q10: What are community norms and why are they important?
• Q11: To which kind of data do the Panton Principles apply?
• Q12: Who decides whether to make certain data Open?
• Q13: Where can I see examples of Open data?
• Q14: What are some of the options for hosting and serving Open Data?
• Q15. What sort of material is data? Can graphs, tables, etc. be marked as Open Data.
• Q16. I have used third-party data in my research – can I combine it with my data and stamp it as Open Data?
• For Data Generators
• Q1: Why should I want my data to be marked as Open Data?
• Q2: Do I have to do anything to make my data Open Data?
• Q3: Is there a way to automate the process?
• Q4: How far back can I go in labeling data as Open Data?
• Q5: When should I label data as Open Data?
• For Data Users
• Q1: How do I know that data is Open Data?
• Q2: Are there any restrictions on what I can do with Open Data?
• Q3: I’m a robot – can I tell what data is Open Data?
• For Publishers
• Q1: Why should publishers care about Open Data?
• Q2: I publish Open Access journals – does that automatically mean the data are Open Data?
• Q3: My Editor and Board are insisting that authors deposit their data – should it be Open Data?
• Q4: How do we mark our data as Open Data?
• For Repositories
• Q1: I want to deposit my data in my Institutional Repository – will it be Open Data?
• Q2: Are the main discipline repositories Open Data?

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 http://pantonprinciples.org/faq/ .

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.