[OPEN-ILS-DOCUMENTATION] ***SPAM*** Re: Forming Teams by Topic

[Soulliere, Robert]

Hi All,


I am wondering if we have come to a decision regarding the DIG repository? I brought this up last month, but did not see a definitive answer develop. Jason has brought it up again and I hope we can come up with definitive repository based home for docbook documentation files.

I also asked if DIGers could be given access to the SVN repository to commit Documentation to the doc directory. Dan mentioned that we can ask for access.

I followed up with this request on the list:

"During the DIG meeting I volunteered to commit the documentation to the repository, so if I could be granted access that would be great. Let me know if you need more information from me such as  preferred username."

I didn't hear back from anyone regarding access. Hopefully, it wasn't an issue with my trustworthiness;-) I am at least 90% sure that I will not delete the entire Evergreen repository by accident or overwrite it with My own version. However, creating a branch off of trunk for documentation as Jason suggests might be a good safety precaution.

I also have a GitHub account and an evergreen branch, but my documentation files don't seem to be making it up stream despite my pull requests.

I wonder if there is still a debate regarding using a DVCS (http://en.wikipedia.org/wiki/Distributed_revision_control) vs a more centralized approach. Can this be solved with a vote among developers to determine the tool we will use for documentation files? Either approach works for me, but I think the closer the documentation is to the code, the better.

The teams suggestion is great. A Systems Administration documentation team was established last year and we have divided up the chapters. We also have names assigned to various chapters on the documentation outline page. This has been extremely helpful in ensuring that there is minimal duplication of work. The other benefit is that a few people have volunteered to send my existing documentation content. This will help reduce the amount if work for me and will allow us to improve the documentation by giving us several sources of content to integrate into the chapters. In short, I suggest following these 3 strategies:

        1) Team up
        2) Inform others about what you are working on
        3) Share what you have


In regards to Content Sensitive Help, Jason++ for creating this discussion and creating the details page to start this discussion. KCLS++ for taking the leadership role in this. From a documentation workflow perspective, I wonder what is possible here. I am thinking that in a perfect world documentation is written once and can be published in various forms many times. I would envision the workflow to be as follows:

1. Authoritative Documentation is written in DocBook XML
3. XML files are added to repository
2. XML in repository is processed into human readable documentation in HTML or PDF. (hopefully this is automated in a cron job)
3. HTML files or PDF files are packaged with Evergreen tarball and made available online

I guess my question is if the HTML or PDF files can be used for the Master Documentation and the Context Sensitive Documentation (links to processed HTML files packages with Evergreen) or if there will be 2 separate streams of Documentation writing.


Regards,
Robert














I think it may be worth creating a subversion or git or bazaar branch
of trunk for documentation, hand out the commit bit to DIG'ers, and
have a self-updating server follow those commits, at least for staff
client files (where changes don't usually require sys-admin
intervention).  I'd want other developers to weigh in here; we're
getting very close to continuous integration type work with this
notion.

> Also, how could those of us working on this project with Darlene most easily gain access to what they
> are working on without creating more work for KCLS staff (who have their hands very full right now!).

Ah, is this question for me?  If they're front-line for this and are
already putting the files into an Evergreen instance, perhaps they
could expose that system to others.  That'd save me from having to
update acq.open-ils.org (or some other trunk server) very often (or
figuring out how to automate it).

One thing we could do is have the html files on whatever test system
we use have nothing but meta-refresh tags to wiki pages.  Then every
now and then the DIG'ers bless some version of that content to put
into the actual source repository (trunk, and stable branches once the
context-help feature becomes stable).

A wiki would be very low-barrier for editing.

--
Jason Etheridge
 | VP, Tactical Development
 | Equinox Software, Inc. / The Evergreen Experts
 | phone:  1-877-OPEN-ILS (673-6457)
 | email:  jason at esilibrary.com
 | web:  http://www.esilibrary.com
_______________________________________________
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.