| Prev | Chapter�15.�Documentation Standards | Next |
|---|
+ +
By Claus Rasmussen, with additions by Roberto Mello and the OpenACS Community -
- OpenACS™ is a powerful system with +
+ 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 @@ -41,7 +42,7 @@ 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 @@ -50,31 +51,31 @@ efforts. These processes are outlined as project management phases:
- Requirements phase is about setting goals and + Requirements phase is about setting goals and specifications, and includes exploration of scenarios, use cases etc. As an example, see the OpenACS Documentation Requirements Template which focuses on systems requirements for developers.
- Strategy phase is about creating an approach + Strategy phase is about creating an approach to doing work. It sets behavioral guidelines and boundaries that help keep perspective on how efforts are directed. OpenACS developers discuss strategy when coordinating efforts such as code revisioning and new features.
- Planning phase is about explicitly stating + Planning phase is about explicitly stating the way to implement the strategy as a set of methods. OpenACS system design requires planning. For example, see OpenACS documentation template planning relating to package design.
- Implementation phase is about performing the + Implementation phase is about performing the work according to the plan, where decisions on how to handle unforseen circumstances are guided by the strategy and requirements.
- Verification phase measures how well the plan + Verification phase measures how well the plan was implemented. Success is measured by A) verifying if the project has met the established goals, and B) reviewing for ongoing problem areas etc. OpenACS follows verification @@ -88,7 +89,7 @@ phases are mainly organized and fulfilled by Joel Aufrecht. Hopefully the following sections will help spur greater direct participation by the OpenACS community. -
By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. @@ -97,7 +98,7 @@ 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 + qmail is a recommended example of "rated high" online documentation.
Avoid requirements that significantly increase the labor @@ -129,14 +130,14 @@
Do not make informal exclamations about difficulty/ease for users to complete tasks or understand... for - example, "Simply...". Readers come from many different + example, "Simply...". Readers come from many different backgrounds --remember that the greater audience is likely as varied as the readers on the internet--- If important, state pre-conditions or knowledge requirements etc. if different than the rest of the - context of the document. For example, "requires basic + context of the document. For example, "requires basic competency with a text-based editor such as vi or emacs - via telnet" + via telnet"
Show where to find current information instead of writing about current info that becomes obsolete. If the information @@ -194,10 +195,10 @@
Use generic DocBook syntax to maximize reader familiarity with the documents.
- <book><title><part label="Part 1"><etc...>
+ <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. @@ -225,10 +226,10 @@ solution, customer cost, convenience, value). A comprehensive community communications system; How this system is valuable to users; Reasons others use OpenACS - (with quotes in their own words) "...the most important + (with quotes in their own words) "...the most important thing that the ACS does is manage users, i.e. provide a way to group, view and manipulate members of the web community. - -- Talli Somekh, September 19, 2001" using it to + -- Talli Somekh, September 19, 2001" using it to communicate, cooperate, collaborate... OpenACS offers directed content functionality with the OpenACS templating system. ... OpenACS is more than a data collection and @@ -248,14 +249,14 @@
From a marketing perspective,
- differentiate "product" by highlighting features, + differentiate "product" by highlighting features, performance quality, conformance to standards, durability (handling of technological obsolescence), reliability, repairability, style of use, design (strategy in design, specifications, integrated, well-matched systems etc).
- differentiate "service" by highlighting software + differentiate "service" by highlighting software availability (licensing and completeness from mature to early adopters or development versions), community incident support, project collaborative opportunities, and @@ -339,7 +340,7 @@ 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. @@ -351,7 +352,7 @@ and other documentation for more detail.
Describe a structural overview of a working system and how - the components work together. "The Layered Cake view" a + the components work together. "The Layered Cake view" a general network view of system; a table showing system levels versus roles to help with understanding how the subsystems are interconnected. @@ -377,15 +378,15 @@ subsystems, work/group communication skills et cetera
Describe how to set up typical site moderation and - administration including parameters, permissions, "Hello - World" page + administration including parameters, permissions, "Hello + World" page
Show directory structure of a typical package, explanation of the various file types in a package (tcl,adp,xql) and how those relate to the previously described subsystems, when they get refreshed etc.
- Ways to build a "Hello World" page + Ways to build a "Hello World" page
Show examples of how the OpenACS templating system is used, including portal sections of pages. For example, create a @@ -404,30 +405,30 @@
FAQs: Administration tasks commonly discussed on boards: admin page flow, how to change the looks of a subsite with a - new master.adp, options on "user pages" , a quick + 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 + state installation prerequisites. For example: "You should read through the installation process to familiarize yourself with the installation process, before beginning an - installation." + installation."
list critical decisions (perhaps as questions) that need to be made before starting: which OS, which DB, which aolserver version, system name, dependencies et cetera. Maybe summarize - options as tables or decision-trees. For example, "As you + options as tables or decision-trees. For example, "As you proceed throughout the installation, you will be acting on decisions that have an impact on how the remaining part of the system is installed. Here is a list of questions you - should answer before beginning." + should answer before beginning."
list pre-installation assumptions
@@ -437,7 +438,7 @@ 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. @@ -473,7 +474,7 @@ 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 + 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 @@ -482,7 +483,7 @@
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. @@ -521,7 +522,7 @@ including planning, core functions, testing, usability, and creating case studies
- Standard package conventions, where to see "model" code, and + Standard package conventions, where to see "model" code, and guidelines (or where to find them) for:
programming tcl/sql @@ -554,10 +555,10 @@ 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”). + methods and cycles (Section�, “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 @@ -567,14 +568,14 @@ 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. -
All OpenACS documentation will be marked up to conform to the DocBook XML DTD. Theoretically, any strict DTD would have been sufficient. We could even write our own, or just use the OpenACS templating system via the Edit-This-Page package. However, - + is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:
@@ -625,9 +626,9 @@
should be able to extract details of a specific reference from
a bibliographic (table) and present a footnote at the
point where referenced. DocBook 4.2 allows for this with
- bibliocoverage,
- bibliorelation, and
- bibliosource. DocBook:
+ bibliocoverage,
+ bibliorelation, and
+ bibliosource. DocBook:
The Definitive Guide is a good start for learning how
to represent paper-based books online.
@@ -637,16 +638,16 @@ 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: - + the same elements are valid in the XML DTD as long as you remember to: +
Always close your tags with corresponding end-tags and to - not use other tag minimization + not use other tag minimization
Write all elements and attributes in lowercase
Quote all attributes -
You are going to need the following to work with the OpenACS Docbook XML documentation:
@@ -660,7 +661,7 @@ to HTML. We have been using a stylesheet based upon NWalsh's chunk.xsl.
- xsltproc - The processor that
+ 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.
@@ -669,7 +670,7 @@
mode. We have a intro to the PSGML
Mode in Emacs as part of our documentation. You can
read about other editing tools in the LDP Author Guide.
-
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 @@ -683,188 +684,188 @@ 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 +
+ 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 + book : Docs for one package - templating | - +--chapter : One section - for developers + +--chapter : One section - for developers | ---------+------------------------------------------------------ | - +--sect1 : Single document - requirements + +--sect1 : Single document - requirements | - +--sect2 : Sections - functional requirements + +--sect2 : Sections - functional requirements | - +--sect3 : Subsections - Programmer's API + +--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
+ 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 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>.
+
+ + 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.
+
+ 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 Section�, “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.
+
+ 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
+ xreflabel-attribute. E.g. the top level of the document you're
reading right now looks like this:
-<sect1 id="docbook-primer" xreflabel="aD DocBook Primer"> +<sect1 id="docbook-primer" xreflabel="aD DocBook Primer"> <title>aD 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.
+ <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.
-
- + 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 will use the tag
- <computeroutput>.
- This takes the place of the HTML-tag <code>
+ <computeroutput>.
+ This takes the place of the HTML-tag <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
+ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
automatically.
-
+ 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
+
+ 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>. +<xref linkend="packages-making-a-package"></xref>.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 + 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, + 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:
-Find information about what a package looks like in -<xref linkend="packages-looks"></xref>. +<xref linkend="packages-looks"></xref>.
And the output is:
- Find information about what a package looks like in -the section called “What a Package Looks Like”. +Section�, “What a Package Looks Like”.
- Note that since I haven't provided an xreflabel for the subsection,
- packages-looks, the
+ 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>):
-
<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 ampersands in your hyper links. These are reserved for referencing
- entities, which is exactly how you'll make an ampersand: &
+
NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing + entities, which is exactly how you'll make an ampersand: & -
+ NOTE: Currently this section currently only takes HTML-output into consideration - not a printed version
- Another Note: Also, it's still not a 100 percent sure that this is how we are going to + Another Note: Also, it's still not a 100 percent sure that this is how we are going to do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
-
+
To insert a graphic we use the elements
- <mediaobject>,
- <imageobject>,
+ <mediaobject>,
+ <imageobject>,
and
- <imagedata>.
+ <imagedata>.
The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG)
and one for print (EPS). Finally you should provide a brief description wrapped in
- <textobject> -
+ <textobject> -
in HTML this will be the ALT text.
<mediaobject>
<imageobject>
- <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
+ <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
</imageobject>
<imageobject>
- <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
+ <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
</imageobject>
<textobject>
<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 + 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>
+
+ 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>:
+ <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
+
+ 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>:
+ <variablelist>, + <varlistentry>, + <term> and + <listitem>:<variablelist> <varlistentry> @@ -878,14 +879,14 @@ </varlistentry> </variablelist> -
+
DocBook supports several types of tables, but in most cases, the
- <informaltable>
+ <informaltable>
is enough:
-<informaltable frame="all">
- <tgroup cols="3">
+<informaltable frame="all">
+ <tgroup cols="3">
<tbody>
<row>
@@ -913,26 +914,26 @@
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
If you want cells to span more than one row or column, it gets a bit more complicated - check out
- <table>
+ <table>
for an example.
-
+
Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -
- <emphasis>.
+ <emphasis>.
- The <emphasis> tag defaults to italics when parsed. If you're looking for
- emphasizing with bold type, use <emphasis role="strong">.
-
+ The <emphasis> tag defaults to italics when parsed. If you're looking for + emphasizing with bold type, use <emphasis role="strong">. +
Marking up index-words may not have any importance for the HTML-output, but in order to make it easier to make a nice print-version of the documentation, you should mark up words in your documents that you would like to see show up in an index one day.
Use
- <indexterm>,
- <primary> and
- <secondary>
+ <indexterm>,
+ <primary> and
+ <secondary>
for this. See these links for an explanation.
-
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 formats. @@ -947,7 +948,7 @@
bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
- This example uses Daniel Veillard's xsltproc command available + 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. @@ -960,10 +961,10 @@
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 + docbook elements and their "look" in HTML and lots of good links for tools.
David Lutterkort @@ -984,14 +985,14 @@
In the process of transforming your HTML into XML, HTML tidy - can be a handy tool to make your HTML "regexp'able". + can be a handy tool to make your HTML "regexp'able". Brandoch Calef has made a Perl script that gets you most of the way. -
| Document Revision # | Action Taken, Notes | When? | By Whom? | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0.4 |
+
| 12/24/2001 | Roberto Mello | ||||||||||||||||||||
| 0.2 | Changed recommendation from <phrase> to <emphasis role="strong"> | 01/19/2000 | Claus Rasmussen | ||||||||||||||||||||
| 0.1 | Creation | 12/2000 | Claus Rasmussen |