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 <[email protected]> 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: [email protected] > [[email protected]] On Behalf Of Karen > Collier [[email protected]] > 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 > [email protected] > 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 > [email protected] > http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation > _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
