RE: [docbook-apps] Producing Open Source Software

One of the big hurdles for advocating the use of DocBook in “public” open source projects is that there are plenty of wiki based alternatives that are free, have short learning curves, and do not require “building”. Developers can easily contribute to the pool of documentation. The wiki approach does have some drawbacks when it comes to ease of versioning, organization, revision control, etc. but for many projects its ROI is fairly high. Some of the weaknesses of the wiki based approach can be overcome with regular pruning and shaping. (I’ve heard the term wiki gardener tossed about.)

I work on a “commercial” open source distribution and find that DocBook works very well. We automated the build process, used the structural nature of XML to enforce some template guidelines, and allow the writers to use any validating XML editor they feel comfortable with. We manage version control via SVN. The use of an open standard that is easily exported gives us some cred in the open source world which is good. Originally I attempted to get the “public” community around the project to use DocBook and was rejected for the reasons state in the first paragraph. For the “commercial” part we have a more resources and a desire to provide the cut above resources, so the extra expense of XML publishing is a wash.

From: Karen Schneider [mailto:kgschneider@gmail.com]
Sent: Thursday, March 05, 2009 7:49 AM
To: DavePawson
Cc: Thomas Schraitle; docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Producing Open Source Software

On Thu, Mar 5, 2009 at 6:58 AM, DavePawson <davep@dpawson.co.uk> wrote:

Thomas Schraitle wrote:

Although the above statement contains some truth, open source projects fail because of something different: the lack of documentation. :)

Treading very carefully :-)

Maybe "fail" is not the word... but certainly open source projects miss some opportunities by not having good documentation.

I know, it's only one reason. This impression is probably influenced from my writer's point of view, but when you don't have (at least) something, it makes it really hard.

"Writer's point of view" is a key phrase here.

Which may be a bit hard. Put a devs hat on and the important thing
is working code. The thought (sometimes ) goes, I'll do the docs later.

Well, look at it empirically. A project goes live without good documentation. It succeeds (at least from the developer point of view). What is the message? Documentation is not essential.

So having good documentation people on the project is just as important
(some would say) as having the good coders.

You will never lose an argument with a writer about the value of writing -- or about the resources required to produce it. (In my personal writing life, I recently calculated that literary essays typically take 3 years on average from first draft to publication -- assuming they have a snowball's chance in Hades of being published.) One comment made to me by a developer with a documentation background is that writing in general is undervalued, a statement I fully agree with. That has a double whammy. Writing is both perceived as unnecessary (the project "succeeded," didn't it?) and also perceived as trivial to produce. Which is interesting, on reflection, because the open source code production process is very highly merit-based and appropriately stingy about its "commits." A novice asking very basic questions about open source will ask me, "Who gets to decide?" I then explain the commit process and it makes sense. Yet translate that to documentation... well, we can all write, can't we? So it must be something easy than everyone can (and will) do and requires very little review, iteration, or gatekeeping.

(This has its parallels in the journalism world, as well, but that would be a far more serious digression. Let's just say that 100 blogs -- and I am a blogger -- do not equal one dedicated investigative journalist, and if you want to have that argument with me, write me personally.)

So now not only is documentation production not the glitzy frontline stuff that gets the praise and attention, but those advocating a serious approach to documentation also have to justify a fairly significant use of resources that will seem overblown to people who perceive documentation as something that can be cranked out by anyone on a Sunday afternoon in a coffeeshop. (Design, user experience, and aesthetics also have similar challenges in many projects. I make no reference to specific projects, having found these issues legion, as I believe is true with many of you.)

This actually segues back into Docbook (moving the discussion back into trunk, as it were :) ). It is challenging to make the argument for XML-based, standards-oriented, single-source documentation *on top of* the argument for expending resources on integrating documentation in a production guideline, period. A newcomer to Docbook has a lot of questions that are not easily answered (yes, I'm writing about myself in the third person...). Also, as we get out our calculators and start to add up the cost... XML production: ka-ching! XSL transforms: ka-ching! Editors that actually do what you want them to: ka-ching! Oh, and of course you want styles with that? Ka-ching! Ka-ching! To a writer, all absolutely reasonable expenses, but it's a resource path that needs to be followed eyes wide open with full disclosure to stakeholders as early as possible ("no really, Dad, the dog will only need puppy chow and water...").

What can initially seem easy and obvious gets more challenging and more complex the closer we get. (Shift to third person plural, my bad.) What is the status of 4 versus 5? When will that change? Why are the tools arcane, complex, or spendy (pick 1 out of 3)? Is it truly possible to integrate "community" writers who are not comfortable hand-coding XML into an XML-based project? Someone wants to do X in our documentation. X is not well-documented for Docbook (the ultimate irony). We ask, the crickets chirp. What are we to assume? How do we proceed?

So we (cough) are placed in the dual role of advocating for Docbook and documentation while probing hard as we can to determine if this is even the right path.

My gut tells me that standards-based, single-source documentation is hugely valuable for any project. Actual ROI stories might help.

docbook-apps message