It’s often hard to find good writing about the state of online documentation. Andy Oram writes for O’Reilly OnLamp, and he has contributed a couple of very interesting articles on the motivations of free documentation writers, and the state of free documentation.
Why Do People Write Free Documentation? Results of a Survey was published on 14 June 2007 and contains some very interesting research results.
Although I found the results very interesting, it was the preamble that I found most worthwhile. The assumptions Andy makes about the current state of free documentation online echoes very closely the motivations for creating FLOSS Manuals. Andy outlines four issues that reflect the general state of online docs today :
- The same questions get asked over and over
- Users don’t know where to start
- Information quality is uneven
- Optimal solutions are often undiscovered
I agree with these issues, but there are two issues I think he overlooked :
Licensing Interoperability
The current licensing situation for free documentation is pretty bad, the main issue being that there is no standard license that everyone agrees to use for documentation on the web. This would not be such a problem if licenses were compatible, enabling the easy transition of content from one source to the other, and allowing the combining of material released under differing licenses. However, this is not the situation now, as Lawrence Lessig mentioned in 1995:
"Even if all the creative work you want to remix is licensed under a copyleft license, because those licenses are different licenses, you can’t take creative work from one, and remix it in another. Wikipedia, for example, is licensed under the FDL. It requires derivatives be licensed under the FDL only. And the same is true of the Creative Commons Attribution-ShareAlike license that governs Opsound content, as well as much of the creativity within Flickr. All of these licenses were written without regard to the fundamental value of every significant advance in the digital age — interoperability" http://creativecommons.org/weblog/entry/5709
With free software, the GPL is the standard license, and since no such agreed ‘standard’ exists for documentation, then improving a document using multiple sources cannot occur.
FLOSS Manuals has decided to use the GPL. Since there is no ‘standard’ for docs (I have written about this in an earlier FLOSS Manuals post about the problems with the GNU Free Documentation License), then we might as well side with the programmers until this interoperability issue is resolved. Documentation is after all, often included with software, and it’s easier for programmers if they don’t have to worry about license compatibility problems between the documentation and the source code. However, one tactic we still might employ is to dual-license in Creative Commons so that bloggers etc could more easily copy and adapt documentation for their own use.
“It’s not a bug. It’s an undocumented feature.”
Andy Oram omitted the ever frustrating fact that often the documentation just doesn’t exist. This is always going to be the case as the first step of a software development project is seldom to write the user manual. Documentation is usually last on the to-do list, and sometimes it falls off the checklist all together. This might be understandable if the project was new. However, there are many times I have looked for documentation and found it doesn’t exist anywhere, even for relatively mature software. The only remedy for this is to hope that more software developers take documentation more seriously and develop a documentation team alongside their coding team. The other option is that community-led projects like FLOSS Manuals fill the gap. This is what we are trying to achieve but our efforts are only needed because the state of documentation online is so bad. In a better world, there would be no need for such an effort.
I enjoyed Andy Oram’s article very much and the results of the survey are well worth reading. You may want to map the findings against “What motivates Wikipedians: motivations for Wikipedia content contribution” (PDF) by Oded Nov. You can find more of Andy Oram’s writing here (thoroughly recommended): http://www.oreillynet.com/pub/au/36