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,
TC
**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
919-716-5518
[email protected]
-----Original Message-----
From: [email protected]
[mailto:[email protected]] On Behalf Of
[email protected]
Sent: Tuesday, May 12, 2009 7:59 AM
To: [email protected]
Subject: Evangelism Digest, Vol 22, Issue 12
Send Evangelism mailing list submissions to
[email protected]
To subscribe or unsubscribe via the World Wide Web, visit
http://lists.plone.org/mailman/listinfo/evangelism
or, via email, send a message with subject or body 'help' to
[email protected]
You can reach the person managing the list at
[email protected]
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 <[email protected]>
Subject: Re: Re: Re: [Evangelism] Plone Messaging
To: ctxlken <[email protected]>
Cc: [email protected]
Message-ID:
<[email protected]>
Content-Type: text/plain; charset=ISO-8859-1
On Sat, May 9, 2009 at 8:58 PM, ctxlken <[email protected]> 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. 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.
J.
------------------------------
_______________________________________________
Evangelism mailing list
[email protected]
http://lists.plone.org/mailman/listinfo/evangelism
End of Evangelism Digest, Vol 22, Issue 12
******************************************
_______________________________________________
Evangelism mailing list
[email protected]
http://lists.plone.org/mailman/listinfo/evangelism
