[OPEN-ILS-DOCUMENTATION] documented developmnt

[Lori Bowen Ayre]

Robert,

You may not see DIG as a standards setting body but in fact you are using
some kind of standard to "Fix and reformat as needed."  I think just having
something in place so people know what to shoot for when doing the
documentation piece would be useful. Even if it wasn't a standard that
determines acceptance of the contribution. Maybe use "guideline" or
"template" instead of "standard?"

And just FYI, I TOTALLY support the low threshold approach to participation.
 My take is that the confusion over how to do something right-ish, is an
impediment to participation.  I believe people want to know what they can do
to make their contribution the most useful as possible and can hold back
when they are confused or unsure about the best way to proceed.

Lori

On Wed, Feb 9, 2011 at 1:23 PM, Soulliere, Robert <
robert.soulliere at mohawkcollege.ca> wrote:

>
>
> 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>
> 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
>
> (707) 763-6869 // 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.
>
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>
>


-- 

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

<Lori.Ayre at galecia.com>Specializing in open source ILS solutions, RFID,
filtering,
workflow optimization, and materials handling
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110209/c20ca839/attachment-0001.htm