Musicians’ Guide First DocBook Draft Is Ready!

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.

Advertisements

2 Comments

  1. I wanted to give a shout-out here for excellent project blogging – it’s been a pleasure to follow your progress and thinking about the Musicians’ Guide, and it’s gotten me to point a few others at it (if you keep doing this, the contributions will come). It also makes a great record of how documentation of this sort gets written, what’s involved, and how someone learns to do it – so I’ll be pointing people to your blog posts on this for quite some time to come. :)

  2. Thanks Mel! As an occasional reader of your blog, I appreciate you saying this.

    Also… note for everybody… the Docs website isn’t updating correctly, so the draft isn’t posted yet. It could happen at *any time*!

Comments are closed.