[OPEN-ILS-DOCUMENTATION] Documentation repositories and bug tracking (was: Re: Documentation Hackfest & Going Forward)

[Dan Scott]

On Sun, 2010-04-25 at 10:01 -0400, Soulliere, Robert 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.
> 

I'm not aware of any requests for commit access to this folder from
anyone on the doc team, which is probably why there are no active doc
team members who currently have commit access. The first step is to ask.

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

Note that Gitorious is another Git-based repository which, unlike
GitHub, offers its platform under the Affero General Public License. I
think it's worth considering using free software platforms to build your
own free software.

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

LaunchPad offers Bazaar instead of Git as a distributed version control
system. Otherwise, it includes a good bug reporting system, support for
translation, and the chance for some integration (one set of user IDs,
etc) with the existing Evergreen bug repository and translation system.

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

If you decide to go the route of a completely separate repository, it
would be nice if the repositories were linked in some way - at least by
a page that says "go here for the documentation, go here for the code".
We need to discuss how bug tracking works, too; documentation projects
can use a bug tracking system to help organize their work, both on the
small scale (people opening bugs to report problems in the
documentation) and at the larger scale. One could, for example, file an
enhancement request for a "Administering Evergreen" section that in turn
linked to a set of other smaller enhancements ("Customizing hold and
circulation notifications", "Setting password strength requirements",
etc) for the pieces of documentation that it depends on.

Also note that it's quite common for a bug to be filed against a project
that needs to be turned into a bug against the documentation. At the
minimum, we need to have documentation team members participating in the
code repository.

That said, there was an undercurrent of discussion at the conference
amongst some of the developers about moving more formally to something
like Bazaar or Git with topic branches rather than just using it to
develop at the fringes. So there's probably a need for a discussion
about where the code is going to live in the future, and it makes sense
(IMHO) for the documentation team to be part of that discussion. At the
very least, I think we need one landing page in the wiki or on the
Evergreen Web site that points to the various places where code and
documentation can be found.