View · Index

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:

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.

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/ 

previous March 2024
Sun Mon Tue Wed Thu Fri Sat
25 26 27 28 29 1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
31 1 2 3 4 5 6

Popular tags

17 , 5.10 , 5.10.0 , 5.9.0 , 5.9.1 , ad_form , ADP , ajax , aolserver , asynchronous , bgdelivery , bootstrap , bugtracker , CentOS , COMET , compatibility , CSP , CSRF , cvs , debian , docker , docker-compose , emacs , engineering-standards , exec , fedora , FreeBSD , guidelines , host-node-map , hstore
No registered users in community xowiki
in last 30 minutes
Contributors

OpenACS.org