On Thu, Mar 5, 2009 at 6:58 AM, DavePawson <[email protected]> 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.
--
--
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| [email protected]
| Web: http://www.esilibrary.com
| Be a part of the Evergreen International Conference, May 20-22, 2009!
| http://www.solinet.net/evergreen
