>Agile Documentation

>Some may say that Agile and Documentation don’t go together. That you can’t take an agile approach to creating documentation. Tonny Madsen’s blog entry “Missing Books Considered Harmful”, brings up some very good points about the state of documentation. The problem with documenting something is how quickly and relevant that information is kept up to date. Traditionally there is a long lead time between when a book is written and when it is released. However, a few authors have taken a different approach to doing documentation.

One way to approach the time lag that is typically unavoidable is to take a more agile approach to documentation. Release both an Online Version, a PDF Version (pay if necessary), and a printed hard copy. Examples of where this has been done successfully are:

DocBook: The Definitive Guide by Norman Walsh

Docbook XSL: The Complete Guide by Bob Stayton.

In some cases by selling the PDF version of the books, a better stream of income can be had by the author compared to just having the printed book. Plus it makes it much more accessible to a wider audience. Personally, I reference Bob Stayton’s HTML docbook stylsheet book very frequently, but because the book was available online, it allowed me to get the information I needed quickly. It also allowed me to see if I wanted to buy the a hard copy reference (which I plan to do).

Norman Walsh created and made available the DocBook: The Definitive Guide for DocBook 4.5 online, and is currently posting new chapters and updates online for DocBook v5.0. This allows the author to get feedback for the potential readers. But it also provides relevant information sooner rather than later.

So, if you are writing a technical book, consider publishing it online first, and then working with the publisher to produce a hard copy. Also, if you haven’t considered it, consider writting your book using DocBook, the available stylesheets will allow you to generate it in multiple formats from one source.

This entry was posted in agile, docbook, documentation, eclipse. Bookmark the permalink.

2 Responses to >Agile Documentation

  1. Tonny Madsen says:

    >David, I think you agile documentation approach can help quite a bit… but it still leaves out one of the important parameters: the developers must take the time to update the documentation… or find a tech writer that can do it.From some of the comments I have received on the blog entry, I have to say that quite a few of the authors/developers seems to prefer to developer rather than write 🙂

  2. David Carver says:

    >Tonny, yeah getting developers to write documentation is like pulling teeth at times. That is why it has to be as easy as possible, and a deliverable like any other piece of code.Even if somebody is just writting a few short articles, over a period of months during the development cycle, it can help. Gather the articles, and combine them into one comprehensive book. I’ve seen it done for numerous topics.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s