| Prev | Chapter 13. Documentation Standards | Next |
|---|
- By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS Community -
- -+
+ By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS community +
OpenACS™ is a powerful system with incredible possibilities and applications, but this power comes with some complexity and a steep learning curve that is only attenuated by good documentation. Our goal is to write superb documentation, so that users, developers and administrators of OpenACS installations can enjoy the system. -
- -+
The history of OpenACS documentation: ..began by building on a good documentation base from ArsDigita's ACS in the late 1990's. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and writing documentation on an as needed basis. -
- -+
By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made @@ -38,8 +27,7 @@ optimization quickly rendered documentation obsolete for developers. The code became the substitute and source for documentation. -
-+
With thousands of lines of code and few developers tracking changes, features and advances to the OpenACS system went unnoticed or were not well understood except by the code @@ -49,26 +37,19 @@ working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS community's main method of sharing knowledge. -
-+
This document attempts to shape ongoing documentation efforts by using principles of continual improvement to re-engineer documentation production. -
-Documentation production shares many of the challenges of software development, such as managing contributions, revisions and the (editorial) release cycle. This is yet another experiment in improving documentation --this time by using principles of continual improvement to focus the on-going efforts. These processes are outlined as project management phases: -
-+
Requirements phase is about setting goals and specifications, and includes exploration of scenarios, use cases etc. As an example, see the @@ -101,40 +82,30 @@ cases, the OpenACS community verifies the project as a success through feedback including bug reports, user and administrator comments, and code changes. -
+
OpenACS forum discussions on documentation requirements and strategies are summarized in the following sections. Production phases are mainly organized and fulfilled by a designated documentation maintainer. Hopefully the following sections will help spur greater direct participation by the OpenACS community. -
-- By the OpenACS Community. This section is a collection of +
+ By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. -
-+
OpenACS documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
-+
clarity in presentation. Life with qmail is a recommended example of "rated high" online documentation.
Avoid requirements that significantly increase the labor required to maintain documentation. -
+
Use best practices learned from the print world, web, and other media, about use of gamma, space, writing style etc. -
-+
Consistency in publishing -Establishing and adhering to publishing standards
Use standardized language -Use international English @@ -166,8 +137,7 @@ context of the document. For example, "requires basic competency with a text-based editor such as vi or emacs via telnet" -
+
Show where to find current information instead of writing about current info that becomes obsolete. If the information is not found elsewhere, then create one place for it, where @@ -176,15 +146,14 @@ to maintain up-to-date documentation. In other words, state facts in appropriately focused, designated areas only, then refer to them by reference (with links). -
-+
Note: Sometimes facts should be stated multiple ways, to accommodate different reading style preferences. The should still be in 1 area, using a common layout of perhaps summary, introduction and discussion requiring increasing expertise, complexity or specificity.
- Consistency in link descriptions -When link urls refer to + Consistency in link descriptions -When link URLs refer to whole documents, make the link (anchor wrapped title) that points to a document with the same title and/or heading of the document. @@ -228,25 +197,16 @@ <book><title><part label="Part 1"><etc...>
-
+ By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. -
-+
OpenACS end-user documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
-+
End-users should not have to read docs to use the system. -
-+
Include how to get help. How and where to find answers, contact others, what to do if one gets an AOLserver or other error when using the system. Include types of available @@ -296,7 +256,7 @@ well-matched systems etc).
differentiate "service" by highlighting software - availability (licensing and completeness from mature to early + availability (licensing and completeness from mature too early adopters or development versions), community incident support, project collaborative opportunities, and contractor support availability @@ -346,11 +306,9 @@ different emphasis on the various criteria, which is why providing a framework to help decide is probably more useful than an actual comparison. -
+
Package documentation requirements have additional requirements. -
-+
A list of all packages, their names, their purposes, what they can and cannot do (strengths, limitations), what differentiates them from similar packages, minimal @@ -381,21 +339,14 @@ development document templates: a Requirements Template and Detailed Design Document. -
+ By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. -
-+
OpenACS administrators' documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
-+
For each requirement below, include links to developer tutorials and other documentation for more detail.
@@ -412,10 +363,10 @@
Create a list of administrative tools that are useful to administrating OpenACS, including developer support, - schema-browser and api browser. Link to AOLserver's config + schema-browser and API browser. Link to AOLserver's config file documentation.
- Resources on high level subjects such as web services, + Resources on high-level subjects such as web services, security guidelines
Describe typical skill sets (and perhaps mapped to @@ -456,22 +407,14 @@ new master.adp, options on "user pages" , a quick introduction to the functions and processes. info about the user variables, file locations -
+ By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. -
-+
OpenACS installation documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
-+
state installation prerequisites. For example: "You should read through the installation process to familiarize yourself with the installation process, before beginning an @@ -494,86 +437,59 @@ for OpenACS, RDBMS(s) install and configure, Webserver install and configure, OpenACS install and configure, post-install work -
+ By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. -
-+
OpenACS developer tutorial documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
-+
list learning prerequisites to customize, fix, and improve OACS modules, and create new ones. You are expected to have read and understand the information [minimum requirements similar to adept at Using OpenACS Administrating Guide] before reading this guide. -
-+
Refer to development documentation instead of duplicating here -
-+
List suggestions for installing and setting up a development environment; these can be annotated links to the installation documentation -
-+
Provide working examples that highlight the various subsystems, Tcl environment, OpenACS protocols, AOLserver template and ns_* commands, OpenACS templating, sql queries, db triggers, scheduling protocols, how to use the page contract, how to get the accessing user_id etc -
-+
Show how to construct basic SQL queries using the db API, -
-- The life of an http request to a dynamic, templated page -
-+
+ The life of an HTTP request to a dynamic, templated page +
General rules to follow for stability, scalability -
-+
Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package development, by referring to developer resources. -
-+
Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a PostgreSQL equivalent tutorial about developing a new OpenACS package including discussion of the significance of the package documentation templates -
-+
Include a summary of important links used by developers -
-+
Note any deprecated tools and methods by linking to prior versions instead of describing them in current docs -
-+ By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. -
-+
OpenACS developer documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
-+
list documentation assumptions, such as familiarity with modifying OpenACS packages. All kernel docs are here etc.
@@ -638,31 +554,20 @@ Document kernel coding requirements, strategy and guidelines to help code changers make decisions that meet kernel designers' criteria -
OpenACS documentation development is subject to the constraints of the software project development and release methods and cycles (the section called “Using CVS with OpenACS”). Essentially, all phases of work may be active to accommodate the asynchronous nature of multiple subprojects evolving by the efforts of a global base of participants with culturally diverse time references and scheduling idiosyncrasies. -
-+
The documentation strategy is to use project methods to involve others by collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project. -
-OpenACS documentation is taking a dual approach to publishing. Documentation that is subject to rapid change and participation by the OpenACS community is managed through the OpenACS @@ -672,13 +577,11 @@ DocBook XML DTD. The remaining discussion is about publishing using Docbook. -
-+ is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook: -
-+
It is open-source.
The DocBook community mailing lists @@ -695,11 +598,9 @@
It is well tested technology. It has been in development since the early 1990's). -
+
Reasons why we are using Docbook XML instead of Docbook SGML: -
-+
Consistency and history. We started with a collection of DocBook XML files that ArsDigita wrote. Trying to re-write them to conform to the SGML DTD would be unnecessary work. @@ -712,16 +613,14 @@ The tool chain has matured. xsltproc and other XML based tools have improved to the point where they are about as good as the SGML tools. Both can output html and pdf formats. -
+
Albeit, the road to using DocBook has had some trials. In 2002, Docbook still was not fully capable of representing online books as practiced by book publishers and expected from readers with regards to usability on the web. That meant DocBook did not entirely meet OpenACS publishing requirements at that time. -
-+
In 2004, Docbook released version 4.4, which complies with all
the OpenACS publishing requirements.
Producing a web friendly book hierarchy arguably remains DocBooks'
@@ -734,103 +633,65 @@
bibliosource. DocBook:
The Definitive Guide is a good start for learning how
to represent paper-based books online.
-
+
The following DocBook primer walks you through the basics, and should cover the needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD as long as you remember to: - -
- -You are going to need the following to work with the OpenACS Docbook XML documentation: -
- -+
Docbook XML DTD - The document type definition for XML. You can find an RPM or DEB package or you can download a zip file from the site linked from here. -
-+
XSL Stylesheets (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon NWalsh's chunk.xsl. -
-+
xsltproc - The processor that
will take an XML document and, given a xsl stylesheet, convert
it to HTML. It needs libxml2 and libxslt (available in RPM and
DEB formats or from xmlsoft.org.
-
+
Some editing tool. A popular one is Emacs with the psgml and nXML modes. The LDP Author Guide and DocBook Wiki list some alternates. -
-After you have the tools mentioned above, you need to define a title for your document. Then start thinking about the possible sections and subsections you will have in your document. Make sure you coordinate with the OpenACS Gatekeepers to make sure you are not writing something that someone else is already writing. Also, if you desire to use the OpenACS CVS repository, please e-mail the gatekeeper in charge of documentation. -
-+
You can look at some templates for documents (in Docbook XML) in the sources for acs-core-docs, especially the Detailed Design Documentation Template and the System/Application Requirements Template. -
-The documentation for each package will make up a little "book" that is structured like this - examples are emphasized: - + -
- -+book : Docs for one package - templating | +--chapter : One section - for developers @@ -844,83 +705,52 @@ +--sect3 : Subsections - Programmer's API | ... : ... -- -+
The actual content is split up into documents that start at a
sect1-level. These are then tied together in a top-level document that
contains all the information above the line. This will be explained in more detail in a later document,
- and we will provide a set of templates for documenting an entire package.
For now you can take a look at the + and we will provide a set of templates for documenting an entire package.
For now you can take a look at the sources of these DocBook documents to get an idea of how they are tied together. -
-
+
Given that your job starts at the sect1-level, all your documents should open with a
<sect1>-tag and end
with the corresponding </sect1>.
-
+
You need to feed every <sect1> two attributes. The first attribute,
id, is standard and can be used with all elements. It comes in very
handy when interlinking between documents (more about this when talking about links in the section called “Links”).
The value of id has to be unique
throughout the book you're making since the id's in your
sect1's will turn into filenames when the book is parsed into HTML.
-
+
The other attribute is xreflabel. The value of this is the text that will appear
as the link when referring to this sect1.
-
+
Right after the opening tag you put the title of the document - this is usually the same as
xreflabel-attribute. E.g. the top level of the document you're
reading right now looks like this:
-
+<sect1 id="docbook-primer" xreflabel="DocBook Primer"> <title>DocBook Primer</title> ... </sect1> -- -
+
Inside this container your document will be split up into
<sect2>'s,
each with the same requirements - id and xreflabel
attributes, and a <title>-tag inside. Actually, the xreflabel is never required in sections, but it makes linking to that section a lot easier.
-
+
When it comes to naming your
sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.
-
+
For displaying a snippet of code, a filename or anything else you just want to appear as a part of
a sentence, we use
<computeroutput>
@@ -929,129 +759,66 @@
These replace the HTML-tag <code> tag,
depending on whether the tag is describing computer output or
computer code.
-
+
For bigger chunks of code such as SQL-blocks, the tag
<programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
automatically.
-
For expressing user interaction via a terminal window, we wrap +
For expressing user interaction via a terminal window, we wrap
the <screen>
tag around text that has been wrapped by combinations of <computeroutput>
and <userinput>
-
+ Linking falls into two different categories: inside the book you're making and outside: -
- - -+
By having unique id's you can cross-reference any part of your book
with a simple tag, regardless of where that part is.
-
Check out how I link to a subsection of the Developer's Guide:
- - -Put this in your XML:
- -+Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
- Find information about creating a package in <xref linkend="packages-making-a-package"></xref>. -- -And the output is:
- -+And the output is:
- Find information about creating a package in Making a Package. -- -+
Note that even though this is an empty tag, you have to either: -
- -+
Provide the end-tag, </xref>, or
-
+
Put a slash before the ending-bracket: <xref linkend="blahblah"/>
-
If the section you link to hasn't a specified xreflabel-attribute,
- the link is going to look like this:
Put this in your XML:
-+
If the section you link to hasn't a specified xreflabel-attribute,
+ the link is going to look like this:
Put this in your XML:
-Find information about what a package looks like in <xref linkend="packages-looks"></xref>. -- -
And the output is:
- -+
And the output is:
- Find information about what a package looks like in the section called “What a Package Looks Like”. -- - -
+
Note that since I haven't provided an xreflabel for the subsection,
packages-looks, the
parser will try its best to explain where the link takes you.
-
+
If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
a little different
(<ulink>):
-
<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>
-
<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>- -
- ....will create a hyper-link to Oracle in the HTML-version of the documentation. -
- -NOTE: Do NOT use +
NOTE: Do NOT use
ampersands in your hyperlinks. These are reserved for
referencing entities.
To create an ampersand, use the entity &
-
Note: The graphics guidelines are not written in stone. Use another valid approach if it works better for you. -
- -
+
To insert a graphic we use the elements
<mediaobject>,
<imageobject>,
@@ -1061,9 +828,7 @@
Two versions of all graphics are required. One for the Web
(usually a JPEG or GIF), and a brief text description. The
description becomes the ALT text. You can also supply a version for print (EPS).
-
+<mediaobject> <imageobject> <imagedata fileref="images/rp-flow.gif" format="GIF" align="center"/> @@ -1075,62 +840,41 @@ <phrase>This is an image of the flow in the Request Processor</phrase> </textobject> </mediaobject> -- -+
Put your graphics in a separate directory ("images") and link to them only with relative paths. -
- -+ Here's how you make the DocBook equivalent of the three usual HTML-lists: -
- -+
Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as
<para>, and that the tags are called
<itemizedlist>
and
<listitem>:
-
+<itemizedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -- -
+
The ordered list is like the preceding, except that you use
- <orderedlist> instead:
+<orderedlist>instead:<orderedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </orderedlist> -- -
+
This kind of list is called a variablelist and these are the tags you'll need to
make it happen:
<variablelist>,
<varlistentry>,
<term> and
- <listitem>:
+<listitem>:<variablelist> <varlistentry> @@ -1144,24 +888,12 @@ </varlistentry> </variablelist> -- -
+
DocBook supports several types of tables, but in most cases, the
<informaltable>
is enough:
-
+<informaltable frame="all"> <tgroup cols="3"> <tbody> @@ -1187,128 +919,62 @@ </tbody> </tgroup> </informaltable> -- -+
With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: -
- -| a1 | b1 | c1 |
| a2 | b2 | c2 |
| a3 | b3 | c3 |
+
| a1 | b1 | c1 |
| a2 | b2 | c2 |
| a3 | b3 | c3 |
If you want cells to span more than one row or column, it gets a bit more complicated - check out
<table>
for an example.
-
+
Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -
<emphasis>.
-
+
The <emphasis> tag defaults to italics when parsed. If you're looking for
emphasizing with bold type, use <emphasis role="strong">.
-
Words that are marked as index-words are referenced in an index in the final, parsed document. -
- -+
Use
<indexterm>,
<primary> and
<secondary>
for this. See these links for an explanation.
-
This section is quoted almost verbatim from the LDP Author Guide.
-+
This section is quoted almost verbatim from the LDP Author Guide.
Once you have the Docbook Tools - installed, you can convert your xml documents to HTML or other + installed, you can convert your XML documents to HTML or other formats. -
- -+
With the DocBook XSL stylesheets, generation of multiple files is controlled by the stylesheet. If you want to generate a single file, you call one stylesheet. If you want to generate multiple files, you call a different stylesheet. -
- -+
To generate a single HTML file from your DocBook XML file, use the command: -
- -+- - -bash$xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml-Note
-+
- -Note
This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. -
-+
To generate a set of linked HTML pages, with a separate page for each <chapter>, <sect1> or <appendix> tag, use the following command: -
- -+- -bash$xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml-+
You could also look at the acs-core-docs Makefile for examples of how these documents are generated. -
- -
+
The LDP Author Guide has a lot of good information, a table of docbook elements and their "look" in HTML and lots of good links for tools. -
-+
James Clark wrote nXML Mode, an alternative to PSGML Mode. nXML Mode can validate a file as it is edited. @@ -1324,13 +990,10 @@ Converts docbook documents to a number of formats. NOTE: I only got these to work with Docbook SGML, NOT with Docbook XML. If you are able to make it work with our XML, please let us know. -
-+
AptConvert from PIXware is a Java editor that will produce DocBook documents and let you transform them into HTML and PDF for a local preview before you submit. -
-+
In the process of transforming your HTML into XML, HTML tidy can be a handy tool to make your HTML "regexp'able". @@ -1339,10 +1002,4 @@ script with directions (now via archive.org) that gets you most of the way. -
-