There is nothing so naked as Rough Cuts

The stereotype of an author, solitary and banging away at their typewriter, is only a little bit different in the digital age. Although the typewriter has been swapped out for a keyboard and a monitor, the solitary nature of writing for print is still true. Your work is your own and you are responsible for it. Editors give feedback and sometimes they are right and you are wrong, and sometimes they are right and your ego doesn't care. Sulking is (often) inevitable.

Writing for print is not the same as writing in public, on a Web site or a Wiki, where many eyeballs make all bugs shallow. But in the spirit of release early and release often, the first five chapters of Front End Drupal have been put online in the Safari library system. There is nothing so naked as putting up content that has not gone through a copy editor. "Occasionally" is my nemesis and I'm eternally grateful there is no "broccoli" in this book because I typically fail several times before getting the speling of either of them right. If you have a Safari account and have the time to look through the Rough Cut of Front End Drupal, I'd be eternally grateful. I prefer my mistakes to meet their demise at the digital phase of this project and not move forward to print.

It's true that the book I'm working on with Konstantin is not free as in beer or speech, but the process of writing so far has taught me a lot about documentation. The process of this project has taught me a lot about the things I like, and the things I want to change about online documentation. When I first started the book I scoured the Internet to see how content had been structured before me. I wanted to see the popular solutions to common problems. I wanted to see what people needed to know. As time progressed I found myself relying mostly on the API documentation for quick references here and there as the chapters became more my "own." Was it my ego that gave up looking for best practices? Or was it simply information overload that made me stop looking at what others had done?

The book has allowed me the opportunity to think about "good" and "useful." I'm starting to form a vision of how to make the user experience of "help" better. In the past I've focused more on interactions, or documentation, but not how we interact with documentation. Addisun has had some amazing cues for my imagination and I've contributed a few thoughts to the Drupal redesign process. (Iteration #8 is now up, but doesn't have new layout stuff for docs against version 7. You may recognize the pink pen of FAIL from some of my Launchpad bug reports in the version 7 comments for the Drupal.org redesign.) One of the things that my experience this fall has taught is this: good documentation is seriously very hard. It's hard to write as a single author and it's hard to write sanely as a community.

We don't yet have a model of best practices for "help" or "documentation" or whatever you want to call that stuff that users turn to when the system is too complicated, or the UI sucks so badly that it is not "intuitive", or the task is so complex that it requires an unknown workflow that goes beyond the imagination of the user. I have spent my time in the trenches of DocBook. I love me some XML markup and could talk your EAR off about combining it with learning styles (and now my new friend video) to produce sheer, glowing awesomeness that would allow people to practically learn by osmosis...

But DocBook XML with Bazaar repositories is not exactly a friendly place for technical authors. Markup is not something that an author should have to do. Someone who cares about formatting and output? Yes. Someone who is interested in markup for learning styles? Sure. But an author should not have to crack open vim to describe a sequence of steps necessary to accomplish a task. (The fact that I'm writing the draft of my book in vim before copying and pasting the contents into OOo and saving as MS Word is not relevant to this discussion. I do it this way because I find vim less distracting than OpenOffice.org.) An author should not have to be an entire production team. We don't ask our kernel hackers to design desktop GUIs...Aside: the LDP is moving toward a Wiki for rough drafts of content and then spitting out DocBook XML that can be distributed through its network of mirrors. It will be interesting to see if this shift revitalizes interest in the project and attracts new authors.

Working on the book has been an adventure (one that has approximately 20,000 more words to it). It has captured my imagination not in the theming of Drupal (that was already interesting) but it has reminded me of how hard it is to produce good support material for our free software. It has given me the opportunity to look at projects that I've not had time for ("procrastination" is the technical term for this). It has reminded me of the challenges of multi-lingual documentation ... it has consumed me ...

But mostly it has made me wonder: why can I bang out 800+ words for a blog entry about nothing coherent but stare blankly at a page for days trying to come up with a clever introduction on theming Drupal page templates? That's right kids... it's because writing good stuff is hard and blathering on about nothing is easy.

PS For my mother, sister and for Moloney: I promise the next entry will have more crafty (or at least English) content... in the mean time, go watch the fainting goats again.