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:
+<code>
+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
+.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:
+) The wiki isn't going away, it's still an extremely useful tool for
+quickly dumping documentation and notes and for collaboration.
+) 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.
+) Documentation licensing will fall under the GNU FDL.
+) 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 :)
+) 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
+</code>
+Others looked upon his proposal, and judged it good. Thus began the Evergreen manual.