[OPEN-ILS-GENERAL] Writing an Evergreen manual
Excellent suggestion Dan - this is a really necessary next step. DocBook would make an excellent foundation for creating more complete and polished documentation. Cheers, George Duimovich NRCan Library / Bibliothèque RNCan
RE: SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual
I'm also all for this idea, not only for version control (which is certainly a good thing), but also because I find a manual easier to use than the wiki. I'll be happy to contribute by writing a section and/or prettying up stuff from the wiki - I've already been compilling everything I can find on OpenSRF (from various blog posts and the like), so organizing that into a single document might be a good place for me start. I could also work on some of the Core Tasks section, if the outline on the demo below is the one you want to stick with - I'd suggest adding a troubleshooting section, too, for things like Receipts only partially printing and xulrunner crashing and the like - I can also add to that as I learn more about fixing the software. What would be *really* nice would be if we could also put the parts of the manual that concern the staff client into a Help file that could be packaged with it. Especially for the troubleshooting section. -Murphy Some say the world will end in fire and ice. Others say it will be segfaults. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Don McMorris Sent: Tuesday, September 25, 2007 9:21 AM To: open-ils-general@list.georgialibraries.org Subject: SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual Pretty much agree with George. I was thinking a static manual would be nice also, for the same reasons that you've cited (nice printing and document-version synchronization). DocBook is one of the most popular formats, and is well established in the industry. The flexibility of automated transforms to XHTML and PDF make it that much better. DocBook++ GNU_FDL++ Documentation_SVN_Branch++ A quick search also yielded a DocBook Wiki program (http://doc-book.sf.net). It appears to allow you to edit DocBook's right in a wiki-style format. It mentions integration with CVS for version tracking, but one of the demo's mentions also integration with SVN. Might be worth checking out too. In general, I completely agree with Dan. It's rare that I don't ;). --Don PS: Although sent from my company-use e-mail address, the views and opinions expressed herein are my own and may not reflect those of my company. Don McMorris Jr. | Technical Specialist | Equinox Software, Inc. / The Evergreen Experts | phone: 877-OPEN-ILS (673-6457) x709 | email: [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] | web: http://www.esilibrary.com Dan Scott wrote: Hello: The wiki is a great resource for quickly searching and adding information, but as a formal body of documentation it leaves something to be desired. Say, for example, that you wanted to print a nice cataloging and circulation manual - right now you would be hard pressed to pull the wiki pages together in a print-worthy format. In addition, the wiki pages have a nasty way of changing to reflect the current version of the code - so if you have Evergreen 1.0 installed on your site, and the wiki contributors are all working with the cutting edge 1.4 development release, then you might have to dig back through old revisions of each page you read to find the docs that apply to your release of Evergreen. So, as the Evergreen 1.2 release is rapidly approaching, I would like to get a more formal documentation project underway to augment the wiki. I propose that we adopt the DocBook XML standard for technical documentation (as is used by PHP, MySQL, PostgreSQL, and myriad other projects) and the associated XHTML PDF transforms to start producing The Book of Evergreen. If you want to see what the output looks like out-of-the-box, you can see a sample at the following URLs: * PDF: http://open-ils.org/~denials/testbook.pdf * XHTML: http://open-ils.org/~denials/testbook.html And if you haven't seen what DocBook XML source looks like, you can see the source for these sample documents here: * http://open-ils.org/~denials/testbook.xml (Please note that I whipped up the table of contents for the manual in a few minutes; it's not meant to be an exhaustive overview or anything resembling a final product! I think the wiki would be an ideal place to work out the details of a quality ToC.) As you can see, the DocBook structure is semantically rich and pretty easy to work with. I'll try to flesh out the source with some more expressive sections in the near future so there will be some templates to work with for things like code samples, commands, links, etc. I'll also try to put together some documentation for how to put together the XHTML and PDF transforms. Assuming that there's a consensus about moving forward with this model for the manual, I don't think writing in DocBook should be required for those who don't have the time to learn DocBook; we should be able to accept good doc contributions in plain text or other formats
Re: SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual
On 9/25/07, Murphy, Sally [EMAIL PROTECTED] wrote: What would be *really* nice would be if we could also put the parts of the manual that concern the staff client into a Help file that could be packaged with it. Especially for the troubleshooting section. Incidentally, Mozilla has a RDF-based help viewer we could utilize if we wanted: http://www.mozilla.org/projects/help-viewer/ Since we're committing to XML anyway, maybe it won't be painful to do some transformations here. :) Thanks Murphy! -- Jason Etheridge | VP, Community Support and Advocacy | Equinox Software, Inc. / The Evergreen Experts | phone: 1-877-OPEN-ILS (673-6457) | email: [EMAIL PROTECTED] | web: http://www.esilibrary.com
[OPEN-ILS-GENERAL] Writing an Evergreen manual
Hello: The wiki is a great resource for quickly searching and adding information, but as a formal body of documentation it leaves something to be desired. Say, for example, that you wanted to print a nice cataloging and circulation manual - right now you would be hard pressed to pull the wiki pages together in a print-worthy format. In addition, the wiki pages have a nasty way of changing to reflect the current version of the code - so if you have Evergreen 1.0 installed on your site, and the wiki contributors are all working with the cutting edge 1.4 development release, then you might have to dig back through old revisions of each page you read to find the docs that apply to your release of Evergreen. So, as the Evergreen 1.2 release is rapidly approaching, I would like to get a more formal documentation project underway to augment the wiki. I propose that we adopt the DocBook XML standard for technical documentation (as is used by PHP, MySQL, PostgreSQL, and myriad other projects) and the associated XHTML PDF transforms to start producing The Book of Evergreen. If you want to see what the output looks like out-of-the-box, you can see a sample at the following URLs: * PDF: http://open-ils.org/~denials/testbook.pdf * XHTML: http://open-ils.org/~denials/testbook.html And if you haven't seen what DocBook XML source looks like, you can see the source for these sample documents here: * http://open-ils.org/~denials/testbook.xml (Please note that I whipped up the table of contents for the manual in a few minutes; it's not meant to be an exhaustive overview or anything resembling a final product! I think the wiki would be an ideal place to work out the details of a quality ToC.) As you can see, the DocBook structure is semantically rich and pretty easy to work with. I'll try to flesh out the source with some more expressive sections in the near future so there will be some templates to work with for things like code samples, commands, links, etc. I'll also try to put together some documentation for how to put together the XHTML and PDF transforms. Assuming that there's a consensus about moving forward with this model for the manual, I don't think writing in DocBook should be required for those who don't have the time to learn DocBook; we should be able to accept good doc contributions in plain text or other formats, and convert it to DocBook on the contributor's behalf. For licensing purposes, I suggest the GNU Free Documentation License 1.2 (http://www.gnu.org/licenses/fdl.txt) with no invariant sections and no required cover text. Any contributions to the manual would have to be contributed under this license. This also means that we would have to seek explicit permission from contributors of the documentation that has already been contributed to the wiki if we want to include any of that in the manual. I hope that we will be able to add a doc repository to svn.open-ils.org, if the good people of Evergreen are willing. At the same time, I hope to be able to start working on getting the infrastructure in place on the open-ils.org site to regularly build and publish the manual. Fresh documentation is always a rewarding sight for a documentation writer. This process may also be useful for providing integrated online help for the staff client - even if, to begin with, the help consists of simply the manual and isn't contextual at all. So, to summarize: 1) The wiki isn't going away, it's still an extremely useful tool for quickly dumping documentation and notes and for collaboration. 2) DocBook is the de facto standard XML schema and publishing tool set for open source projects, so we will be able to capitalize on the work others have done before us. 3) Documentation licensing will fall under the GNU FDL. 4) There's work to be done to get this all up and running, but we've made it this far without a manual; another few weeks aren't going to kill us :) 5) There's plenty of ways to contribute to the documentation project; from commenting on the manual table of contents, to editing, to writing, to creating prettier CSS for the XHTML, to implementing searchable XHTML on the open-ils.org site, to setting up user notes functionality for each XHTML page (although - warning - user notes require a massive amount of effort to maintain in the PHP and PostgreSQL projects!). If you think you might be able to help, I'll welcome your contributions - no matter how big or small. Of course, this is just a proposal. If everyone is happy with the wiki as-is, that's fine too. I would think you're all crazy - but that's fine :) -- Dan Scott Laurentian University
