[Evangelism] Longish post: Developers and documentation (was Evangelism Digest, Vol 22, Issue 12)

Clark, Tom tomclark at shawu.edu
Wed May 13 19:26:41 UTC 2009

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 product/system. 

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
tomclark at shawu.edu

-----Original Message-----
From: evangelism-bounces at lists.plone.org [mailto:evangelism-bounces at lists.plone.org] On Behalf Of evangelism-request at lists.plone.org
Sent: Tuesday, May 12, 2009 7:59 AM
To: evangelism at lists.plone.org
Subject: Evangelism Digest, Vol 22, Issue 12

Send Evangelism mailing list submissions to
	evangelism at lists.plone.org

To subscribe or unsubscribe via the World Wide Web, visit
or, via email, send a message with subject or body 'help' to
	evangelism-request at lists.plone.org

You can reach the person managing the list at
	evangelism-owner at lists.plone.org

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 <jluvsu2 at gmail.com>
Subject: Re: Re: Re: [Evangelism] Plone Messaging
To: ctxlken <ken.wasetis at contextualcorp.com>
Cc: evangelism at lists.plone.org
	<34501d7e0905110603s4799a2d8h598a9c7d6540649d at mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1

On Sat, May 9, 2009 at 8:58 PM, ctxlken <ken.wasetis at contextualcorp.com> 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
Evangelism at lists.plone.org

End of Evangelism Digest, Vol 22, Issue 12

More information about the Evangelism mailing list