%myvars; ]> By Claus Rasmussen, with additions by Roberto Mello 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. ..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 to the system, existing documentation became dated, and its value significantly reduced. The valiant efforts that were made to keep the documentation current proved too difficult as changes to the system sometimes had far-reaching affects to pages throughout the documentation. System integration and 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 authors. Work was duplicated as a consequence of developers not realizing the significant work completed by others. New developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS community's main method 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: 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. 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. 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. is about performing the work according to the plan, where decisions on how to handle unforseen circumstances are guided by the strategy and requirements. 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 through different means on different projects, but in all 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 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. 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 (without slang or colloquial terms) for ESL (English as a second language) readers (and making translation easier for those interested in translating the documentation for internationalization efforts). All jargon used in documentation needs to be defined. Use standardized terms when available, avoiding implicit understanding of specific OpenACS terms. Document titles (for example on html pages) should include whole document title (as in book title): (chapter title) : (section), so that bookmarks etc. indicate location in a manner similar to pages in books (in print publishing world). Organize document according to the needs of the reader (which may be different than the wishes of the writers). Do not make informal exclamations about difficulty/ease for users to complete tasks or understand... for 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 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 others can refer to it. This structure of information will significantly reduce obsolescence in writing and labor burden 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 whole documents, make the link (anchor wrapped title) that points to a document with the same title and/or heading of the document. Consider OpenACS documentation as a set of books (an encyclopedic set organized like an atlas) that contains volumes (books). Each book contains chapters and sections much like how DocBook examples are shown, where each chapter is a web page. This designation could help create an OpenACs book in print, and help new readers visualize how the documentation is organized. The use licenses between OpenACS and Arsdigita's ACS are not compatible, thereby creating strict limits on how much OpenACS developers should have access to Arsdigita code and resources. The OpenACS documentation has a new legal requirement: to eliminate any dependency on learning about the system from Arsdigita ACS examples to minimize any inference of license noncompliance, while recognizing the important work accomplished by Philip Greenspun, Arsdigita, and the early ACS adopters. Use a consistent general outline for each book. Introduction (includes purpose/goal), Glossary of terms, Credits, License, Copyright, Revision History Table of Contents (TOC)s for each book: the end-users, content and site administrators, marketing, beginning developers, and developers. Priorities of order and content vary based on each of the different readers mentioned. The developers guide should be organized to be most useful to the priorities of developers, while being consistent with the general documentation requirements including publishing strategy, style etc. Use generic DocBook syntax to maximize reader familiarity with the documents. <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 support (open-source, private commercial etc.) including references. Explain/foster understanding of the overall structure of the system. This would be an overview of the system components, how it works, and how to find out more or dig deeper... To promote the system by presenting the history of the system, and writing about some tacit knowledge re: OpenACS.org and the opensource culture. Introduce and inspire readers about the uses, benefits, and the possibilities this system brings (think customer 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 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 communicate, cooperate, collaborate... OpenACS offers directed content functionality with the OpenACS templating system. ... OpenACS is more than a data collection and presentation tool. OpenACS has management facilities that are absent in other portals. ...The beauty of OpenACS is the simplicity (and scalability) of the platform on which it is built and the library of tried and tested community building tools that are waiting to be added. It seems that most portals just add another layer of complexity to the cake. See Slides on OACS features...a set of slides on OACS features that can be used for beginners who want to know OACS is about and what they can do with it. Screen captures that highlight features. Example shows BBoard, calendar, news, file storage, wimpy point, ticket tracking. An OpenACS tour; an abbreviated, interactive set of demo pages. To build awareness about OpenACS, consider product differentiation: form, features, performance quality, conformance quality (to standards and requirements), durability, reliability, repairability, style, design: the deliberate planning of these product attributes. Include jargon definitions, glossary, FAQs, site map/index, including where to find Instructions for using the packages. FAQ should refer like answers to the same place for consistency, brevity and maintainability. Explain/tutorial on how the UI works (links do more than go to places, they are active), Page flow, descriptions of form elements; browser/interface strengths and limitations (cookies, other) Discuss criteria used to decide which features are important, and the quality of the implementation from a users perspective. Each project implementation places a 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 description, current version, implementation status, author/maintainers, link(s) to more info. Current version available at the repository. Include dependencies/requirements, known conflicts, and comments from the real world edited into a longer description to quickly learn if a package is appropriate for specific projects. Create a long bulleted list of features. Feature list should go deeper than high-level feature lists and look at the quality of the implementations (from the user's perspective, not the programmer's). Example issues an end-user may have questions about: Ticket Tracker and Ticket Tracker Lite, why would I want one of them vs the other? And, before I specify to download and install it, what credit card gateways are supported by the current e-commerce module? There are some packages where the name is clear enough, but what are the limitations of the standard package? End-user docs should not be duplicative. The package description information and almost everything about a package for administrators and developers is already described in the package itself through two basic 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. Describe a structural overview of a working system and how 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. Provide a comprehensive description of typical administrative processes for operating an OpenACS system responsibly, including reading logs and command line views that describe status of various active processes. 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 file documentation. Resources on high level subjects such as web services, security guidelines Describe typical skill sets (and perhaps mapped to standardized job titles) for administrating an OpenACS system (human-resources style). For a subsite admin/moderator attributes might include trustworthy, sociable, familiarity with the applications and subsystems, work/group communication skills et cetera Describe how to set up typical site moderation and 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 Show examples of how the OpenACS templating system is used, including portal sections of pages. For example, create a customised auto-refreshing startpage using lars-blogger, a photo gallery, and latest posts from a forum. This should rely heavily on documentation existing elsewhere to keep current. This would essentially be a heavily annotated list of links. Show ways of modifying the look and feel across pages of an OpenACS website. Refer to the skins package tutorial. Describe a methodology for diagnosing problems, finding error statements and interpreting them --for OpenACS and the underlying processes. 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 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 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 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." list pre-installation assumptions Show chronological overview of the process of installing a system to full working status: Install operating system with supporting software, configure with preparations for OpenACS, RDBMS(s) install and configure, Webserver install and configure, OpenACS install and configure, post-install work 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, DocBookDTD 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. A growing community surrounds DocBook (has mailing lists) A number of free and commercial tools are available for editing and publishing DocBook documents. It enables us to publish in a variety of formats. XML separates content from presentation: It relieves each contributor of the burden of presentation, freeing each writer to focus on content and sharing knowledge. 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. XML does not require extra effort. Writing in XML is almost identical to SGML, with a couple extra rules. More details in the LDP Author Guide. 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.2, which complies with all the OpenACS publishing requirements. Producing a web friendly book hierarchy arguably remains DocBooks' weakest point. For example, a dynamically built document 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: 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. However, you're always welcome to check out 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: XML guidelines Always close your tags with corresponding end-tags and to 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: 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 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 sure you coordinate with the OpenACS Gatekeepers to make sure you're 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: Document structure book : Docs for one package - templating | +--chapter : One section - for developers | ---------+------------------------------------------------------ | +--sect1 : Single document - requirements | +--sect2 : Sections - functional requirements | +--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 sources of these DocBook documents to get an idea of how they are tied together. SectionsHeadlines Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>. 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 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. xreflabel 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="aD DocBook Primer"> <title>aD DocBook Primer</title> ... </sect1> sect2 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. computeroutputcode 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> 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. Linking Linking falls into two different categories: inside the book you're making and outside: 1. Inside linking, cross-referencing other parts 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. xreflinkendCheck 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: - Find information about creating a package in . 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: -Find information about what a package looks like in <xref linkend="packages-looks"></xref>. And the output is: - Find information about what a package looks like in . 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. 2. Linking outside the documentation ulink 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> ....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: &amp; 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 do it, so if you want to start converting your documents right away, start out with the ones without graphics ;) GraphicsImages To insert a graphic we use the elements <mediaobject>, <imageobject>, and <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> - in HTML this will be the ALT text. <mediaobject> <imageobject> <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/> </imageobject> <imageobject> <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 only with relative paths. lists Here's how you make the DocBook equivalent of the three usual HTML-lists: 1. How to make an <ul> 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> 2. How to make an <ol> The ordered list is like the preceding, except that you use <orderedlist> instead: <orderedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </orderedlist> 3. How to make a <dl> 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>Heading (<dt>) goes here</term> <listitem><para>And stuff (<dd>)goes here</para></listitem> </varlistentry> <varlistentry> <term>Another heading goes here</term> <listitem><para>And more stuff goes here</para></listitem> </varlistentry> </variablelist> informaltabletable DocBook supports several types of tables, but in most cases, the <informaltable> is enough: <informaltable frame="all"> <tgroup cols="3"> <tbody> <row> <entry>a1</entry> <entry>b1</entry> <entry>c1</entry> </row> <row> <entry>a2</entry> <entry>b2</entry> <entry>c2</entry> </row> <row> <entry>a3</entry> <entry>b3</entry> <entry>c3</entry> </row> </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 If you want cells to span more than one row or column, it gets a bit more complicated - check out <table> for an example. emphasisbold, italics 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">. 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> for this. See these links for an explanation. This section is quoted almost verbatim from the LDP Author Guide. Once you have the 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 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. Using Xinclude 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. David Lutterkort wrote an intro to the PSGML Mode in Emacs For checking if your document is well-formed, James Clark's free Java parser, XP, is recommended. (note that it is not a validating parser, but as long as you follow the guidelines set forth in this document, your XML will validate) DocBook Tool for Linux: Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see how you stuff looks. 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". Brandoch Calef has made a Perl script that gets you most of the way. Document Revision # Action Taken, Notes When? By Whom? 0.4 Fixed some typos. 8/3/2002 Vinod Kurup 0.3 Added OpenACS information, updated tools, added extra links and added info to the Publishing section. 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