View · Index

Weblog

Filtered by category Documentation, 1 - 10 of 18 Postings (all, summary)

for beginning developers

Created by OpenACS community, last modified by Antonio Pisano 03 Nov 2023, at 11:55 AM

Tutorials for OpenACS development

Other related tutorials

See also: OpenACS Mentorship Program

Other useful resources

Web Sites

Books

Documentation Project Discussion

Created by OpenACS community, last modified by Gustaf Neumann 06 Oct 2019, at 12:54 PM

Current topic: What approach should we use to upgrade the documentation?

Here are some recent approaches expressed in one form or another for managing the documentation in the context of "the plan":

Approach 0. Why not use docbook, which was the previous way documentation was being handled?

  • docbook 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.
  • docbook 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.
  • docbook is well tested technology. It has been in development since the early 1990's).

problems: 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. Yet, OpenACS documentation does not follow a standard book hierarchy since most of the documentation was written before version 4.2, and re-organizing it in docbook source would be challenging.

Other problems with using docbook:

  • Only developers can make changes, which makes it difficult for the rest of the community to coordinate changes and updates, especially when they are seemingly small (such as typos).
  • OpenACS docbook has long documents, which puts extra stress on using consistent style to separate topics on the same page. For example, readers get confused when trying to follow the installation documents. Some instructions get missed, other instructions are done when they shouldn't have been.
  • OpenACS docbook uses multiple tags for the same function and requires only certain tags to be used in certain contexts. The documentation in HTML is convoluted and displays inconsistent.

Based on the other recent suggestions, there seems to be a general consensus to move away from docbook, but perhaps keep the docbook organization.

Approach 1. from en:Proposed_project_goals

Robert writes:

- First: ..attempt to take the rest of Documentation over to XoWiki..
- Secondly: ..try to setup an automated versioning system. We should end up with categories such as 5.2 Documentation, 5.3 Documentation, HEAD Documentation, etc. My current thinking is that we can work on HEAD category of documentation, once 5.3 is release it becomes categorized as such and a copy of the docs gets created and re-categorized as HEAD once again. This should allow versioning and easy upgrades/editing of docs (well easy may not be the right word, docs are a lot of work)

Robert, "Secondly" is how versioning has been accomplished using docbook.  This method seems to work fine, and we can do it with xowiki docs by creating a set of static pages from the xowiki ones. --Torben

Approach 2

Robert writes:

Documentation: [move] ..the rest of the documents to XoWiki. The idea would be to have categorized documents. We would start by moving the 5.2 docs over and expanding on them. When 5.3 is release we would do an automated copy/paste of the 5.2 docs, re-categorize as 5.3 and start the editing process. This is just preliminary thinking at this point..

 Robert, everyone seems to have their own way of slicing and dicing docs into categories.  We ought to use the existing documentation requirements to guide how the documents are organized, and then they can be categorized any number of ways since multiple categories can be applied to each page. --Torben

Approach 3 (and previously 5). Refactoring original docbook docs en:New_Documentation_Process

STAGE A: CONVERT DOCUMENTATION TO XOWIKI (note: all api docs remain the same) Step #1. Catalog the current documentation.

(Malte writes) ..modify the script Gustaf provided to import the whole documentation in one go into a new XoWiki instance with the structure (page_order) that has been added in XoWiki 0.42 taken from the chapters of the documentation so that we do have an exact mirror of the documentation as it stands now. [Done, see https://openacs.org/test-doc].

Malte, why would we want an exact mirror of something that is not organized well.. too many topics per page and pages inconsistently presented..  requires a new reader to jump around to get familiarized with material. etc etc?  Why not copy the docbook contents into a cleaner outline and work from there (as in approach 3 above)? --Torben

Torben, the /doc section is organized. That you do not like it is obvious and we could rework it later, but until we have the resource to rewrite the whole documentation, it makes much more sense to improve the documentation we have instead of putting it into the graveyard. And we need to come to terms. This discussion does not yield any results at the moment but keep us from doing the actual work: Improving the documentation -- Malte

[Then] ..assign categories to the documentation, allowing for an alternative view on the documents (so you could say "instead of showing the whole documentation only show the documents for a specific category"). Probably this needs some more detailed discussion with Gustaf finding out how this could be achieved in XoWIKI and what would make most sense. Ideally we could provide a different structure based on the target group (e.g. category) but this is probably shooting too far. Getting categorization and page ordering in a decent shape should provide us a lot of possibilities..

Malte, have you seen docs-admin-toc , docs-end-user-toc and docs-eng?  These are outlines of existing pages in XoWiki that represent a revised version of the Table of Contents (TOC) in the docbook version.  Feel free to propose new pages there for us to fill in  content. --Torben

Yes I have seen them. Do they resemble a book in any way to you? They are alternative structures, indeed, but you can impose them on a book view as well, any time. A book is what we need, something people can go to and start reading. If the book starts with four different pages, each outlining a different reading path, even the better. But a book it should be nevertheless, because this is how people still learn. If you do not like the book approach, that is fine, then we should open this question up for a TIP. My main goal at the moment is to finally get this done and start working. And I want to get rid of the myriads of confusing advise given at openacs.org. I have someone to work with me on that in the next two months and I want to have a clear way to go forward. So I will just TIP this. -- Malte
 

See also: en:wikidoc-notice

 

Approach 4 Mental Maps en:Documentation_Project_Plan

This approach was originally posted at en:Documentation_Project. It was moved here as the topic expanded.

..port docbook pages to xowiki manually.. look at each part in detail.. separate to 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.

A short video on how the mind deal best with large amounts of information by "chunking": The Science of Thinking

This work is in progress, with root documentation page here: en:openacs-handbook

A systems strategy of multiple perspectives has these rules:

  • Each xowiki page discusses a single topic.
  • Topics are linked 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.

Multiple perspectives meets these significant documentation requirements:

  • helps identify subsystems and how OpenACS works --becomes a natural tutorial without more words.
  • reduces the burden of keeping documentation up to date since there is only one place to put relevant information for a particular topic --no redundancy
  • pages are not organized by a dominant category morphology that tends to address the perspectives of just a few people. Most any perspective can be represented.
  • Readers do not have to filter out a bunch of information that is irrelevant to them or their task at hand.

Move all but maybe the first and last 2 items from https://openacs.org/doc/dev-guide.html to https://openacs.org/doc/acs-kernel/ (and what ever else is relevant to kernel only); and move the first item to https://openacs.org/doc/acs-admin etc. That way the core docs are presented in a consistent context with the other packages. Also, do not migrate these docs around as a package is designated part of the core (or subsequently removed from it). This would help developers see appropriate context (and meets one of the documentation requirements).

Allow documentation to link directly to the api-docs, to reduce redundancy and links go to current, local API docs. In other words, https://openacs.org/api-doc/package-view?version_id=358136 becomes: /api-doc/index?about_package_key=acs-datetime The feature has been added to OpenACS 5.3 so will be released soon.[DONE]

Move Administrator's Guide to the xowiki [in progress, see en:docs-admin and en:docs-admin-toc ], because this section:

  • has the most duplicated work (topics overlap on various pages). For example, more than one page explains how to add a package, how to restart the server, how to start the server etc.
  • needs to be updated most frequently because of changing installation requirements. For example, PostgreSQL requires different instructions for different revisions, external links change sporadically etc.

Incorporate the work already done in the first wiki ( https://openacs.org/wiki ), where volunteers have already added a wealth of new documentation. Note that some of this will already exist in xowiki from previous importing of docs etc. [TO DO]

We need to get rid of the myriads of different installation instructions. First of all they are not kept up to date (all of them). -- Malte 

for administrators - Table of Contents

Created by OpenACS community, last modified by Gustaf Neumann 29 Sep 2019, at 10:21 AM

docs-admin

    docs-admin-help

    openacs-system-install
        docs-install
            os-nix
            openacs-compatibility-matrix
        openacs-reference-platform
        os-nix-install
        Get_the_Code
        oracle-install
        postgresql-install
        tcl-install
        aolserver-install
        openacs-subsystem-install

        openacs-system-install-debian
        openacs-system-install-redhat
        openacs-system-install-freebsd
        openacs-system-install-osx
        openacs-system-install-suse
        openacs-system-install-win2k
        openacs-system-install-windows-server

    aolserver-admin
    postgresql-admin
    oracle-notes
    openacs_monitoring

    acs-developer-support
    acs-api-browser
    schema-browser


    openacs_monitoring
    openacs-performance-tuning

    doc-credits

for developers - Table of Contents

Created by OpenACS community, last modified by Gustaf Neumann 25 Sep 2019, at 10:14 PM


docs-eng 

    openacs-system
        openacs-subsystem
        tcl
        aolserver
        postgresql
        oracle


    Testing_with_Selenium
    testing-with-tclwebtest

    code-formatting
    Naming
    ADP_Files
    TCL_pages
    TCL_Procs
    SQL_-_XQL
    Web_Forms
    listbuilder


    Package_Testing_Process_

    ide-emacs
    ide-vi

    Official_test_servers

    doc-credits
 

Documentation Project Plan (Approach 4)

Created by OpenACS community, last modified by Gustaf Neumann 25 Sep 2019, at 10:13 PM

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/ 

for everyone

Created by OpenACS community, last modified by Benjamin Brink 22 Jul 2017, at 11:49 PM

OpenACS for everyone

OpenACS (Open Architecture Community System) is:

  • an advanced toolkit for building scalable, community-oriented web applications.
  • a robust, scalable framework (see: en:openacs-system) for building dynamic content driven sites and enterprise-level web applications.
  • a collection of pre-built applications and services that you can build on to create a custom web-site or application.
  • derived from the ArsDigita Community System (ACS). ArsDigita (now part of Red Hat, Inc.) kindly made their work available under the GPL, making all of this possible.

Through a modular architecture, OpenACS has packages for user/groups management, content management, e-commerce, news, FAQs, calendar, forums, bug tracking, wiki (XoWiki), full-text searching etc. See OpenACS repository.

Strengths

Use the OpenACS fourms to contact the OpenACS community. We welcome your feedback and can help with your OpenACS endeavors. Commercial support is also available.

What others say about OpenACS

Others' descriptions of OpenACS

Testimonials posted to forums on OpenACS

Try OpenACS

History of OpenACS

See: History of OpenACS en:docs-history

Bibliography and Credits

See: Documentation Credits en:doc-credits

for administrators

Created by OpenACS community, last modified by Benjamin Brink 07 Jul 2017, at 07:15 AM

Getting admin-level help

Install OpenACS

Setup database environment variables. See end of https://openacs.org/doc/openacs.html,

https://openacs.org/doc/backup-recovery.html, and https://openacs.org/doc/snapshot-backup.html

https://openacs.org/doc/analog-setup.html

For creating custom pages, see developer tutorials https://openacs.org/doc/tutorial.html

Administrating a system

These OpenACS packages are useful for diagnostics and development:

Performance monitoring

Bibliography and Credits

See en:doc-credits.

OpenACS Handbook

Created by OpenACS community, last modified by Benjamin Brink 03 Jul 2017, at 09:29 PM

Documentation Credits doc-credits

Documentation Project Documentation_Project

Most Popular Pages

Created by Gustaf Neumann, last modified by Benjamin Brink 30 Jun 2017, at 07:15 AM

Collaboration Graph

Created by Gustaf Neumann, last modified by Benjamin Brink 30 Jun 2017, at 07:10 AM

You must login to see the collab-graph

Next Page
previous October 2024
Sun Mon Tue Wed Thu Fri Sat
29 30 1 (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

Popular tags

17 , 5.10 , 5.10.0 , 5.10.1 , 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
No registered users in community xowiki
in last 30 minutes
Contributors

OpenACS.org