[OPEN-ILS-DOCUMENTATION] documented developmnt

[Soulliere, Robert]

Personally, I don't envision the DIG as being the "arbiter" of anything or as the setter of standards. Our role is to (as I see it):

1. Receive documentation in any form or format
2.  Fix and reformat as needed
3. Place it into a repository shared by the community
4.  Disseminate/distribute share documentation  in a final form for reading (e.g. HTML, PDF processed from DocBook)
5.  Update and fix documentation as needed.
6. Rinse and repeat for each version of Evergreen

It should not be our intention to add documentation standards to place heavy burdens on developers, or institutions, or companies.  My hope is to find a way to help the documentation process catch up to the development process. From my perspective development has been lightning fast and incredible. The ultimate shared goal should be  to find a way to get documentation from the heads of developers, expert users,  trainers etc... into the hands of the Evergreen users so all can benefit, but in the least burdensome way.

I was also not thinking about this from as  a process issue as much as a tools or resource issue. In other words, could some of the existing resources be better utilized to accomplish the goal of keeping documentation up to the speed with development efficiently and effectively. Dan touched on a few of these such as repositories and launchpad. In short, could DIG folks be more involved in these tools to more effectively keep up?

One example: could we have documentation fixes submitted like code fixes using launchpad or would that create a disaster of complexity in launchpad?... So when a developer adds a feature, they could at the same time introduce a documentation ticket requesting documentation for the feature. The an interaction could follow via launchpad and the documentation person could work with the developer? Would that kind of interaction work as features are developed?

I am also thinking of documentation in its most basic level as describing how a tool is used. I believe in starting simple and starting with  imperfect documentation and editing until it is better. The sooner the imperfect documentation is introduced to the community at large the sooner it can be improved. This is what I envision open -source development to be all about.

Robert










From: open-ils-documentation-bounces at list.georgialibraries.org [mailto:open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Lori Bowen Ayre
Sent: Wednesday, February 09, 2011 3:32 PM
To: Documentation discussion for Evergreen software
Subject: Re: [OPEN-ILS-DOCUMENTATION] documented developmnt

Great discusssion....I'll just jump in here and say that it makes no sense to me that DIG would be the arbiter of what development goes into a release.  I think DIG should be the arbiter of what is considered acceptable documentation, and I agree that there should be a well-defined standard (or more likely several standards).

But I do think we should separate those things.  Maybe we could focus on defining documentation standards so that as we move forward, we can be assured that all developers have something to work with.  That would be an excellent next step.  DIG folks, is that something you'd be game to work on?

As to the rest of this discussion, I'd like to encourage us to continue on this path of defining a process for all phases of development and to encourage us to start even earlier than you are (so far).

I believe the development process begins at the point when a question mark pops up over a user's head with "I wonder if anyone is working on fixing/enhancing/developing ThisThing yet...???"  So, the earlier we can get development projects (or potential development projects) out to the community in an established format and location the better off everyone will be.  People need to know
a) feature set of the current release
b) what features will be added to the next release(s)
c) what is actively being worked on (by all developers), and
d) what are some features or enhancements that users have an interest in seeing developed (and how critical are they and who shares that interest and who has money to pay for their development).  The web team has been calling this one the "wish list."

Items a) and b) may be knowable now (although I personally don't know how to find those answers) and what the web team would like to do is ensure that these things do all become knowable.  So establishing a process that everyone follows is an important first step.

Lori



On Wed, Feb 9, 2011 at 9:56 AM, Grace Dunbar <gdunbar at esilibrary.com<mailto:gdunbar at esilibrary.com>> wrote:
 I think if the community agrees that DIG should be the arbiter of what development goes into a release based on documentation we should at least agree on a basic well-defined standard.



--

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=
Lori Bowen Ayre // Library Technology Consultant
The Galecia Group // www.galecia.com<http://www.galecia.com/>
(707) 763-6869 // Lori.Ayre at galecia.com<mailto:Lori.Ayre at galecia.com>

Specializing in open source ILS solutions, RFID, filtering,
workflow optimization, and materials handling
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=


________________________________
This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message. If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited. If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110209/11b7645a/attachment-0001.htm