documentation:history_of_the_technical_writing_project
Differences
This shows you the differences between two versions of the page.
documentation:history_of_the_technical_writing_project [2007/09/25 23:13] – created dbs | documentation:history_of_the_technical_writing_project [2022/02/10 13:34] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | =====The Book of Evergreen: From Whence It Sprang====== | ||
+ | On September 24, 2007, Dan Scott sent the following email to the open-ils-general list: | ||
+ | |||
+ | < | ||
+ | Hello: | ||
+ | |||
+ | The wiki is a great resource for quickly searching and adding | ||
+ | information, | ||
+ | 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, | ||
+ | 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" | ||
+ | out-of-the-box, | ||
+ | |||
+ | * PDF: http:// | ||
+ | * XHTML: http:// | ||
+ | |||
+ | And if you haven' | ||
+ | see the source for these sample documents here: | ||
+ | * http:// | ||
+ | |||
+ | (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' | ||
+ | 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' | ||
+ | |||
+ | For licensing purposes, I suggest the GNU Free Documentation License | ||
+ | 1.2 (http:// | ||
+ | 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 " | ||
+ | svn.open-ils.org, | ||
+ | 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' | ||
+ | made it this far without a manual; another few weeks aren't going to | ||
+ | kill us :) | ||
+ | |||
+ | 5) There' | ||
+ | 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 | ||
+ | </ | ||
+ | |||
+ | Others looked upon his proposal, and judged it good. Thus began the Evergreen manual. |