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: [email protected] | web: http://www.esilibrary.com _______________________________________________ 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
