Okay, now I joined Andy Oram talking about Splitting Books Open: Thoughts on the Digital Future of Technical Documentation.
He’s talking about the difficulties of “community documentation”. Describes his struggles to find out how Trackback works. How hard it was — there’s an ecology of self-education on the Net, but it’s hard to drill down to the right place. So traditional documentation has some place in the modern technical world.
What are the advantages of a good book? Can this be replicated in community education?
Firstly: Pace. Revealing the answers in the right order. There’s an idea of audience – technical reviews, focus groups and so forth. Background: books can gather together relevant and enlivened background. Structure: like pace, but on a larger scale. “Life in general is getting less structured. Even the military is much more flexible than it used to be.” – so we can tolerant less structured documentation.
Questions answered by good books: What’s the range of problems that this tech solves? How do different parts interact and alter each other’s behaviour? What are the strengths and weaknesses of different solutions”? What am I responsible for once I adopt the technology?
A step toward the solution: Safari. (Just sketching this out, not talking about Safari) – subscription service, profitable, there’s a competitor called SourceBeat which looks interestd.
Stuff that’s wrong with Safari (fun seeing this from an O’Reilly guy). Material is essentially identical to print books. There’s a nice Eclipse plugin, ORA should open source it. Lots of work to do, lots of potential. Other publishers should join Safari, or start their own service to push us to do more from it.
Comments: people saying the thing they really want is Safari offline. Everybody agrees it’s tough because of warez. Andy Oram: “Yeah, but people rip us off all the time! Will it make it worse?”.
Potential future roles for publishers: Authors may contract out to publishers for particular tasks: editing, layout,, art, indexing, tech review. Publishers might help with publicity, getting book reviews.
Improving user education: I am trying to apply what I know about good documentation to USENET, mailing lists, Linux Doc project, etc.
1. Urge active community participants to become formal contributors. O’Reilly often finds people on mailing lists, and pluck them out. Project folk should do this more – find out what motivates them, offer rewards, Wiki concept is intriguing but too new to judge effectiveness. (Comments from audience: Wikipedia good indication they will do well. Wikis tend to sprawl to cover everything. Yeah, but some pages become hotspots. Plone guy: We’re moving away from wiki for documentation, because the amount of refactoring increases exponential, so we’re moving to a more structured HOWTO system, with named authors, ownership etc. Andy Oram: Wiki is a good place to collect information, then someone goes through and pull out the info. Audience seems to agree.
2. Incorporate professionals into community documentation: problem is these professionals cost. Whittle down what is needed to the point where authors can afford professional help — just tiny discrete tasks. Or what about sponsorship? Companies must love decent documentation, right? Audience: companies don’t even give money to their own documentation. Perl’s good documentation was written while the authors were writing O’Reilly books, so there’s a weird kind of sponsorship here.
3. Nurture new users; don’t repel them. Community has to take responsibility for each member’s learning. Dump “RTFM” from your ammunition bag. These may be people you need to hire in six months.
4. Point people to documents: many useful explanations are buried. Create flexible pathways through documentation. Make use of professional developed documentation. Large volumes of documents will be overwhelming.
Plone guy: we have an embarassment of documentation. So we’re structuring, and it might be useful for other projects.
Enhancing rating systems. Let readers rank documents. There are problems, but then there are problems with reputation in the real world. Willingness to tolerate bad advice varies with the subject matter. Documentation in Plone “ages” (the ratings go toward the mean over time).
Ancillary failings of user educations: it favours English-speakers. There are translations, but it’s hard to keep things in sync. Cultural differences aren’t respected: we expect people to ask questions, or stand being flamed. You shouldn’t have to give up your cultural background to learn information. Different learning styles not respected. There are gaps, and haphazard coverage.