[OPEN-ILS-DOCUMENTATION] Evergreen 2.2 documentation changes

[Soulliere, Robert]

Hi Documentation Community,

I want to let people know about some of the changes that will take place for the evergreen documentation in master and as of version 2.2 and beyond.

1) asciidoc: The official format for contributions will be asciidoc. This entails several advantages:

- asciidoc is easier to write. No more complicated DocBook XML tag to memorize.
- asciidoc files can be read more easily as stand alone document compare to raw docbook xml files.
- files in the code can be more easily migrated/imported into the documentation (such as the README file for installation)
- some important contributors are already using asciidoc for their documentation (ESI, Dan Scott)

For authoring in the asciidoc format you can :
Review the official asciidoc usergude: http://www.methods.co.nz/asciidoc/userguide.html
Check out this asciidoc cheat-sheet: http://powerman.name/doc/asciidoc
Or look at some of the files we have added to the repository:  https://github.com/rsoulliere/Evergreen-DocBook (.txt files are asciidoc files)
These files should give you some idea about the structure of files to be included.


2) I have begun to reorganize the documentation. See: http://open-ils.org/dokuwiki/doku.php?id=evergreen-docs_2.2:outline.
Note: This is a work in progress. Please flesh out the chapters/sections under each part. Feel free to reorganize as needed. In other words, hack away!

3) I have adjusted the repo directory structure accordingly in the master of the repository: See: https://github.com/rsoulliere/Evergreen-DocBook
Changes include:

Directories corresponding to the the specific areas of library operation (eliminating the generic "stafftasks" directory):
circulation
cataloging
opac (using the opac)
serials
reports

Directories for this other more general areas:
installation
admin (for files related to system configuration/customization, server admin and local admin)
development (developer stuff)

a "media" directory for images, etc used in any of the chapters of the documentation...


Note that the final documentation product has not changed much at this time:

If you check out the documentation page at:
http://docs.evergreen-ils.org/
you will see that there is a link to 2.2 documentation in both hHTML and PDF formats which is under development. This is produced from the asciidoc files in the master repo.
The toolchain to produce the documentation is asciidoc -> DocBook XML -> (HTML and PDF). The reason the DocBook XML creation step (automated process)  is to produce the PDF files.

Authors will only need to create and edit plain asciidoc files for 2.2 documentation (not XML).

However, DocBook XML is still the format for authoring in 2.1 and other prior versions of the documentation.


Thanks,
Robert


Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011

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.