[OPEN-ILS-DOCUMENTATION] documented developmnt

[Kathy Lussier]

Hi Robert,

> 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 really like the idea of some sort of mechanism where a developer could
start a documentation ticket for a new feature. I also think this kind of
ticketing system could be useful for non-developers who notice a lack of
documentation in a certain area. For example, somebody might submit a ticket
for holds policies. This could also help the content coordinators keep on
top of what  documentation needs are out there.

> 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.

Our previous discussion seemed to focus on developers providing this
documentation, but I can also see a role for early testers in creating the
imperfect documentation. In the absence of documentation, I spent quite a
bit of time testing the acquisitions module and writing up notes to share
with my own group to help us understand how to use acquisitions. The notes
really are a result of much fumbling around, and I'm not even sure they
represent the best workflow that could be used, but, judging from some of
the questions I've seen on the list, they probably would have been helpful
to others who were testing acquisitions. However, it would never occur to me
to add them to the dokuwiki, because I think of that documentation as
"official" documentation that has been tried and tested in a live
environment. If we had a place to post imperfect notes, or to possibly tag
documentation as imperfect notes, I might feel more comfortable about
posting them somewhere. As somebody else tests acquisitions and finds a
better way to do something, they could update the documentation with
improved workflows. This not only would lead to better documentation, but
could also turn the whole process into a shared learning experience. 

Also, in thinking back to my early testing with serials, before Lebbeous
posted his very helpful documentation on the alternate serials control view,
he had posted an e-mail to the Evergreen list that sketched out the basic
steps needed to get started with serials. These steps weren't as detailed as
the final documentation, but they really were what I needed to get started
in serials. I could see these types of notes from developers also being
posted to this "imperfect notes" area of a dokuwiki. The official
documentation was even more helpful, but, when new features are introduced,
I think most people are happy with whatever sketchy notes they can get.

Kathy
-------------------------------------------------------------
Kathy Lussier
Project Coordinator
Massachusetts Library Network Cooperative
(508) 756-0172
(508) 755-3721 (fax)
klussier at masslnc.org
IM: kmlussier (AOL & Yahoo)
Twitter: http://www.twitter.com/kmlussier
 
 
 

> -----Original Message-----
> From: 
> open-ils-documentation-bounces at list.georgialibraries.org 
> [mailto:open-ils-documentation-bounces at list.georgialibraries.o
> rg] On Behalf Of Soulliere, Robert
> Sent: Wednesday, February 09, 2011 4:23 PM
> To: Documentation discussion for Evergreen software
> Subject: Re: [OPEN-ILS-DOCUMENTATION] documented developmnt
> 
>  
> 
> 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.o
> rg] 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 <http://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.
> 
>