JoAnna et. al.

You write:

        >>Personally, I subscribe to the belief that the code isn't done until 
it's documented.         
      >>If we really want to solve our documentation problem, developers have 
to start
        >>contributing documentation for every bit of code they write. Since 
most developers
        >>see   this as asking too much, I doubt we'll ever truly solve our 
documentation issues.

These are my beliefs as well--with maybe not quite so much pessimism about the 
outcome : ).  

An analogy: In a thriving library, one that has either money to buy books 
(which I'll use to represent all the materials that libraries acquire nowadays) 
and/or lots of donated collections, there is *always* a lag between what books 
the library has in it's possession and what their catalog reflects to the their 
public as available for use--the infamous (to librarians anyway) "backlog." 

I think software documentation is like that backlog, at least in the sense 
that, as a practical matter, if you were able to completely get rid of it, it 
would be because your money/donations (new products, software systems etc.) 
dried up and you finally got to quit coping with new changes so you could 
finish the work that should have been done on the old.  But, of course, this 
scenario means your product is failing. So not only is a backlog of 
documentation work inevitable to at least some extent, it's the sign of a 
successful enterprise (as I know JoAnna knows...)

If you start with JoAnna's proposition that the code isn't done til it's 
documented, an appropriate, though, as we are discussing, 'inevitably' 
idealistic standard, then what about some compromise measure?  Just as speed 
limit signs and fines don't eliminate speeding and presumed certainty that 
there would certainly be more of it without any signs, there must be something 
between kvetching about developers not documenting and living with accepting 
nothing from them.

What if developers (between the """triple quotes""", no?), were asked 
(implored?...bribed? required?) to write something like an 'elevator speech,' 
either a prescribed outline and/or results of some prefab Q&A for their 
product? That would give documenters something to start with and a basis for 
both immediate elaboration and further dialog.  Then each product would come 
with an intelligent jumping-off point for creating something useful to the 
user.  That won't eliminate 'backlog' of course, but will give the user 
something to go on in the meantime, and for us Sisyphean toilers in the 
documentation editing business, a basis for producing something to make users 
more productive and a fighting chance to not get completely overwhelmed.

While I'm at it, I'll risk another library-world analogy.  BC (before 
computers), every library had to have cataloger(s), (now called 'metadata 
librarians,' btw) to look at every book that came in and decide what official 
subject heading(s) it should have (and other things) in terms of the mission of 
the local institution.  This was/is called 'original cataloging.'  With the 
development, in the 60s, of the OCLC database, it became possible for one 
cataloger to draft a set of 'metadata' (author, title, subject(s), LC/Dewey #s 
etc.), and everyone else to copy that draft from OCLC and correct/modify it to 
their local circumstances--called 'copy cataloging.'  In fact, for about 10-15 
years, until the development of the online catalog and the web/internet, 
computers in libraries were used, not to directly provide information, but 
simply to efficiently produce the cards--again, BC, they had to be manually 
typed--for the card catalog.  For those of you who may not know, this catalog 
was a huge wooden box that every library had in the middle of the facility.  
While ancient history to some of you, for a long time this big wooden box, 
along with the phone book, were the most common, perhaps 'universal,' at least 
in Western society, popular experience with what is now called a 'database.'

The end of this story, for my purpose here, is that eventually the publishers 
started putting the cataloging information--the author, title etc.-- called 
Cataloging-in-Publication (CIP) data, on the back of the title page (the 't.p. 
verso,' for you traditionalists) of every book they printed (grab the closest 
book and have a look for it). This practice** allows the catalogers (the 
'documenters' of book availability in my analogy here), automatic and free, to 
them anyway, access to the metadata they need to make a good catalog--one that, 
just like good software documentation--makes it easy for 
less-than-completely-knowledgeable users to figure out how to use the 

Of course, the fly-in-the ointment in this analogy, is that the cost of 
generating CIP data is such a drop in the bucket for what publishers do to 
create a physical book. OTOH, with software development, the publisher and the 
author are virtually the same people.  And just as authors write to satisfy 
their own agenda(s) and leave it to someone else (editors and publishers) to 
make their work accessible to a wide audience, JoAnna's bleak outlook on 'truly 
solving' the issue of quality documentation is, to me, really a plea for 
getting someone to be responsible for, as she suggests, completing the 
development process so that wider population, not to say the 'ignorant masses,' 
have a shot at learning how to use it.

So I don't see any magic bullets, but I do see a way in which a similar problem 
has been solved before.

With apologies for any naiveté that comes with being new to this scene,


**I know that CIP isn't really how metadata gets into online catalogs, but I'll 
leave it the way it is for now and hope the example makes my point.

Tom Clark, MLS
Director, Wiggins Library
Shaw University Divinity School

-----Original Message-----
[] On Behalf Of
Sent: Tuesday, May 12, 2009 7:59 AM
Subject: Evangelism Digest, Vol 22, Issue 12

Send Evangelism mailing list submissions to

To subscribe or unsubscribe via the World Wide Web, visit
or, via email, send a message with subject or body 'help' to

You can reach the person managing the list at

When replying, please edit your Subject line so it is more specific than "Re: 
Contents of Evangelism digest..."

Today's Topics:

   1. Re: Re: Re: [Evangelism] Plone Messaging (JoAnna Springsteen)


Message: 1
Date: Mon, 11 May 2009 09:03:56 -0400
From: JoAnna Springsteen <>
Subject: Re: Re: Re: [Evangelism] Plone Messaging
To: ctxlken <>
Content-Type: text/plain; charset=ISO-8859-1

On Sat, May 9, 2009 at 8:58 PM, ctxlken <> wrote:
> One suggestion that might help (if it's not already being done)... for 
> those that are most intimate with the docs and with where we're coming 
> up short, I think it'd be great to log this as a defect/bug in the 
> Plone issue tracker.&nbsp; Then, on 'bug Fridays', we can attack these 
> bugs along with the code issues. Ken

May docs we know we need are already in the tracker, under the documentation 
component. Others editors have indicated in their assessments which are linked 
to from the doc wiki. It's up to editors to assign the work.  We have been 
working on these documents during Tune-Up days already.
Again, it all boils down to not having enough resources. For whatever reason, 
people don't like to document.
Personally, I subscribe to the belief that the code isn't done until it's 
documented. If we really want to solve our documentation problem, developers 
have to start contributing documentation for every bit of code they write. 
Since most developers see this as asking too much, I doubt we'll ever truly 
solve our documentation issues.



Evangelism mailing list

End of Evangelism Digest, Vol 22, Issue 12

Evangelism mailing list

Reply via email to