Documentation Project Plan (Approach 4)

This is Approach 4 of the en:Documentation_Project as defined in Documentation_Project_Discussion.  Users benefit when they can read docs the way the brain likes to work. Contributions to various OpenACS topics that further the plan are welcome.

Background

See Documentation history

Goal

to write superb documentation, so that users, developers and administrators of OpenACS installations can enjoy working with and using the system (with fewer headaches! =)

Scope

OpenACS documentation, a systems view as a collection of subsystems and their parts.

API Documentation: there are no plans to move the API docs to XoWiki. That should remain as is.

DocBook docs at: https://openacs.org/doc/index.html are evolving separately at en:New_Documentation_Process

Requirements

Requirements is about setting specifications and milestones we can verify, and includes exploration of scenarios, use cases etc.

Here are documentation requirements for:

• en:docs-end-user-reqs includes Marketing documentation requirements and Package documentation requirements
• en:docs-admin-reqs
• en:docs-install-reqs
• en:docs-dev-tutorial-reqs
• en:docs-eng-reqs

Available resources

• volunteers dedicated to regularly managing and updating the documentation
• other volunteers who contribute arguably more valuable documentation less frequently (such as magazine articles ;) (and may need some assistance etc. to have their work fit into docs well.)
• openacs.org website, including use of xowiki
• open-source software, text editors, spell checkers, HTML code validators etc.
• Approaches in docs management explored. See en:Documentation_Project_Discussion

Strategy

Strategy is about creating an approach to doing work. It guides behavior and tactical decisions on the work effort.

Shape ongoing documentation efforts by using principles of continual improvement and following general requirements to re-engineer documentation production and management.

OpenACS documentation development is subject to 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 methods that inspire collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project.

subdivide by subsystems and how they are used (context). Why?

"..the human mind can only deal with a relatively small number of independent pieces of data at one time, but if data are chunked together in appropriate ways, the mind can perform higher order abstractions, and these in turn can be chunked together, with successive abstractions, until an entire complex situation is encompassed. The systems approach addresses this property of the human mind by providing strategies for the data gathering, chunking, and abstracting process." George G. Lendaris, On Systemness and the Problem Solver: Tutorial comments 1983.

• How the mind manages large amounts of information by "chunking": The Science of Thinking by Derek Muller / Veritasium (youtube)
• Learning how to learn fast using chunking techniques: How to Learn Anything... Fast by Josh Kaufman / The RSA (youtube)

XoWiki docs can use a systems strategy of multiple perspectives to help identify subsystems and how OpenACS works.

Each XoWiki page discusses a single topic.

These topics are pieced together by any number of other xowiki pages to present an ordered presentation of the topics with a common thread/topic connecting them.

For example, en:openacs-system-install is a page that links together the topics of installing the component software of Openacs. Similarly, each component software, such as en:aolserver, has its own view of some overlapping topics.

XoWiki documents organized by subsystems (and how they are used) are easy to update and maintain since there is only one place to put relevant information for a particular topic.

Pages are not encumbered by a maze of categories that tend to only address one or a few perspectives, since pages link to related pages, and a page that addresses each perspective can link to overlapping topics.

In an ideal world, XoWiki will be able to export a page and all the pages that link to it, to any depth of the linkage tree, to form one document. That way, innumerable documents, each with a valid perspective, can be built for a specific purpose.

Work Breakdown Structure

Or Objectives and Key Results (OKRs) is about explicitly stating the way to implement the strategy as a set of milestones and the methods to use.

Allow document writers to reference package API via api-doc by using package_url, or find the local package_id so a link can be supplied from the local documentation to current, up-to-date API and SQL docs, like: https://openacs.org/api-doc/package-view?version_id=358136 use links like this: /api-doc/index?about_package_key=acs-datetime The feature has been added to cvs head (OpenACS 5.3.x) so will be released soon.[DONE]

Iterate through each topic on each docbook page.

• Port the docbook pages to xowiki manually, because it allows me to look at each part in details and separate to subsystem/object context. Here is the process:
• Browse to docbook url (something in this tree: https://openacs.org/doc/)
• View page source
• Copy the relevant part of source
• Paste that source to your favorite text editor (not word processor).
• Edit the page source, removing DIV tags and TARGET="_blank" attributes. Look for any immediate way to improve the document, make additional edits, check for spelling etc.
• In a browser, open or create the xowiki page. Choose "Source" to view source html. Be sure to make Name starting with "en:"
• Paste edited source into the xowiki page, repeat editing if needed
• Click "ok" to post the xowiki changes.
• That's it! (repeat)

Example documentation outline in wiki

These pages contain links to other pages where items are discussed in context:

Name	for/description
en:docs-end-user	documentation for everyone
en:openacs-system	end-user about OpenACS system, ties together much of the stuff below.
en:docs-end-user-reqs	end-user doc requirements and checklist
en:docs-install	installing OpenACS prerequisits
en:openacs-system-install	installing OpenACS overview
en:openacs-system-install-redhat	installing OpenACS on Redhat
en:docs-install-reqs	installation- docs requirements and checklist
en:docs-admin	administrators
en:docs-admin-reqs	administration - doc requriments and checklist
en:docs-dev-tutorial	tutorials for developers
en:docs-dev-tutorial-reqs	developer tutorials - requirements and checklist
en:docs-eng	developers
en:docs-eng-reqs	developing - requirements and checklist

These pages describe various OpenACS subsystems, and link to external documents where possible and appropriate. Note that an "OpenACS system" en:openacs-system page that outlines the system and ties these together is part of the end-user docs.

Name	subsystem of OpenACS
en:aolserver	AOLserver
en:aolserver-install	installing AOLserver
en:aolserver-admin	administrating AOLserver
en:naviserver	NaviServer
en:naviserver-openacs	installing NaviServer
en:oracle	Oracle relational database
en:oracle-install	installing Oracle
en:oracle-notes	Oracle notes
en:postgresql	PostgreSQL relational database
en:postgresql-install	installing PostgreSQL
en:postgresql-admin	administrating PostgreSQL
en:os-nix	*nix operating system
en:os-nix-install	installing an OS
en:tcl	Tcl language
en:tcl-install	installing Tcl
en:openacs-subsystem	OpenACS subsystem (layer)
en:openacs-subsystem-install	install OpenACS

Auxiliary systems

en:ide-emacs	gnu emacs as IDE
[en:ide-emacs-nxml]	gnu emacs nXML Mode
[en:ide-emacs-psgml]	gnu emacs PSGML Mode
en:ide-vi	vi/vim as IDE

Verification

This is where we measure how well this plan was implemented. Success is measured by

• A) verifying if the project has met the established goals and requirements, and
• B) reviewing for ongoing problem areas etc.

Observations then help to modify the plan for the next documentation revision.

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.

Related links and sources

https://www.divio.com/blog/documentation/