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

[Nicole Engard]

May I put my vote in for git.  I use it often and it's really easy
once you learn the commands (which you can keep in a text doc like I
do).  I also want to remind everyone of the tool I mentioned in the
meeting for editing DocBook without knowing DocBook - for those who
want to use Word, you might want to take a look at this first to try
and save some time by not making others convert a Word doc to DocBook:
http://www.xmlmind.com/xmleditor/

Thanks
Nicole C. Engard

On Sun, Apr 25, 2010 at 10:01 AM, Soulliere, Robert
<robert.soulliere at mohawkcollege.ca> wrote:
> 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
>