By the time you read this, the first DocBook draft of the Musicians’ Guide should be available on the Fedora Docs website, under the “Draft Documentation” heading. The conversion from MediaWiki to DocBook did go much more quickly than I thought it would – very lucky! Since then, I’ve also significantly overhauled a few chapters, have learned about the style I’m using, and have made several other small changes.
Over the next week, work will focus on these areas:
- applying the style consistently across all chapters,
- revising the text to make it as concise as possible (currently a problem),
- incorporating comments from other testers.
The development deadline for Fedora Summer Coding is next Monday 9 August, and this last stretch is going to be a busy one. Careful revision is a very slow, arduous process. I usually end up writing a paragraph three or four times before leaving it. This is the nature of writing, however, and I guess it parallels sofware testing, which usually takes five times longer than writing the code in the first place.
I’m really starting to understand why documentation is often left out of open-source projects, or left to become obsolete once it is written.