[OPEN-ILS-DOCUMENTATION] ***SPAM*** Re: ***SPAM*** RE: ***SPAM*** Documentation Hackfest & Going Forward

[Roma Matott]

Just as a side note, the deadline request was for me.  I work better with deadlines, so I had asked Karen to suggest a date for when we (meaning me) should submit what we have for conversion to DocBook.  It wasn't meant to pressure anyone else :)

Roma
Pioneer Library System
----- Original Message -----
From: "Robert Soulliere" <robert.soulliere at mohawkcollege.ca>
To: "Documentation discussion for Evergreen software" <open-ils-documentation at list.georgialibraries.org>, open-ils-dev-bounces at list.georgialibraries.org
Sent: Sunday, April 25, 2010 10:01:30 AM GMT -05:00 US/Canada Eastern
Subject: [OPEN-ILS-DOCUMENTATION] ***SPAM*** RE: ***SPAM*** Documentation	Hackfest & Going	Forward

Thanks Karen,

I would like to follow up with some requests for all to help us get the ball rolling.

I do believe the first thing that needs to be done is to decide on where the official master documentation will be parked. I think it should be a repository and some DIG folks will need commit privileges to be able to push (upload) documents into it.

There is a subversion (SVN) repository for documentation currently at:
http://svn.open-ils.org/trac/ILS/browser/trunk/docs/1.6.

This seemed to be the intended repository folder for the Book of Evergreen at some point based on the existence of sample documents on that folder. However, I am not aware of any DIG people who currently have commit access to that repository. If that is the final destination for the documentation either someone on the DIG needs commit access to that repository or all documents will have to be committed by someone with access to that repository.

Another option is GitHub. Joe Atzberger sent out an excellent tutorial on how to get started by setting up a fork. I set up a fork of the Evergreen GitHub repository. It seems to be a good tool to use for our purposes. The feature I like about GitHub is that documents can be edited directly from GitHub using a browser (kind of like google docs) which allows quick editing of typos etc... without using the check-in check-out process. This will allow content editors to fix problems once the documents are uploaded to the repository without having to upload the document.

Another option mentioned was Launchpad which is also a great tool, but I thought was more useful as a bug reporting system. I have not had a chance to compare GitHub and Launchpad. Could anyone give a brief "objective" comparison of GitHub and Launchpad? I really don't care about what tool is used as long as DIG have access to commit documents and as long as the repository is universally recognized as the master authorative location for documentation.

Deciding on the universal location for the documentation will have several benefits:

1) Everyone can get a better sense of progress by seeing tangible documentation thus reducing frustration that nothing is getting done.
2) End users could have one location to find documentation even if it is not complete or perfect.
3) Completed documentation could provide a guide or template for others writing documentation and will help to form a universal voice for the entire document.

Some have suggested having a completely different repository outside of the code repository for the documentation. This makes sense too. All we need is to set it up and decide where this will be parked if this is the direction to go in.

Regarding deadlines and assignments:

Assigning deadlines for completed work is a bit tricky since different DIGers will be submitting work in different forms (Word, DocBook, etc...). Submitting content in Word is an early stage and could require a lot more work to get it into DocBook format. Moreover, some content already exists and is a matter of copying and pasting while some involves creating new content.

However, we do need a hard absolute deadline for everyone to indicate what section people are working on by indicating such on the outline:
http://www.open-ils.org/dokuwiki/doku.php?id=evergreen-docs:outline
If you know which sections you are focussing on, please write your name next to the section ASAP. This will allow us to see if we need to volunteer for more sections to fill in gaps. I recommend the deadline for indicating the sections people are working on should be within weeks.

Perhaps we need to take an inventory of capabilities in regards to DocBook and repository committing and maybe indicate those abilities in the roster list:
http://www.open-ils.org/dokuwiki/doku.php?id=evergreen-docs:digparticipants

This will help us to know what we can commit too. For example, I can convert to DocBook and commit to a repository, but if there are very few who can do those tasks I will probably need to reduce my content contributions in order to focus on DocBook conversion and committing. Otherwise, there could be a horrific bottleneck in our work flows.

I copied the Developers list on this email for their guidance since I believe they are the gatekeepers of the repositories and we need their recommendations for the destination of the DocBook files. Please chime in if your are a developer or repository gatekeeper and let us know the best approach.

Thanks,
Robert





________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of Karen Collier [kcollier at kent.lib.md.us]
Sent: April 23, 2010 3:39 PM
To: Public Open-ILS documentation discussion
Subject: [OPEN-ILS-DOCUMENTATION] ***SPAM*** Documentation Hackfest & Going     Forward

A big thank you to everyone who attended the Documentation Interest Group Hackfest at this year's conference.  We had a great turnout and lots of useful discussion.  It was also great to have the chance to put faces with names.

I'll recap the high points as I remember them, but please chip in if I leave anything out or if you have any comments or questions.

In discussion we identified some goals for the group:

- To put together a simple styleguide for contributors.
- To choose a process for version control & automating production of HTML and PDF documents from the DocBook files we create.  Launchpad and Github were mentioned as possibilities.
- To identify deadlines for those participants who feel they work well to deadlines.
- To communicate better with Evergreen developers in order to facilitate documenting the techier side of Evergreen.
- To identify "teams" of participants based on type of contribution and on content area of interest.  By type of contribution we mean content production (writing, editing, and testing) or technical wrangling (conversion to docbook and committing to version control repository).  By content area of interest, we're mainly thinking of whether content producers are working on documentation for end users, system admins, or developers.
- To get busy producing content and sharing it on the mailing list in whatever format or state of readiness it's in, so we can make some visible progress.

I'll send out a "How to Get Started" email soon for those interested in writing editing, and testing documentation, along with suggested deadlines for those who prefer a deadline.  :)

Thanks,
Karen


--
Karen Collier
Public Services Librarian
Kent County Public Library
408 High Street
Chestertown, MD 21620
410-778-3636
_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation

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