Hazi Gharagozlou, Ramiro Gomez, Heiko Kern, Peter Marklund

Summary of Discussion:

All participants recognized that the current documentation for OpenACS is outdated and very difficult to use for a newbie. (I mentioned that I couldn't use ETP because of its documentation). All recognized that Joel Aufrecht's efforts is appreciated and a good path to follow.

The group recognizes that there is a need for three levels of documentation:

• User's guide

It should enumerate all functionalities of a package/module. The parts this document can also be used as link in pages for content-sensitive help (Lars mentioned it as important in his UI discussion). A walk-through of some of the typical user cases would be helpful to clarify obscure functions.

• Admin guide (Managing a site)

Currently we assume admin tasks to be carried out by a developer. However in a large organization an administrative assistant should be able to handle some of the mundane tasks. The role can be called site or sub-site manager. The manager would handle user/group creation and permissioning system.

There is some doubt on whether the manager should also manage packages and mounting sub-sites.

• Developer's guide

Developer guide should be up to date. Perhaps we can use ad_library comments more effectively in developer's document instead of searching for it in API browser.

Finally mention was made of difficulty of using Emacs with all the bells and whistles and bringing all together in a Docbook format.

Recommendations and Decisions:

• Decision to discuss with the Docbook experts in the community (Roberto?), on using other document formats like MS Word, and then using a filter to incorporate the document in a centrally located Docbook project.
• Afterward I spoke with Don Baccus and convened that when he supplies me with a few complex examples of group permissions (i.e. roles), I am willing to write up a mini how-to and change the UI of group management (hopefully making it easier to use)
• The developer documents should contain ER and Page flow diagrams.

To start the effort I have reversed engineered the OpenACS 4.6 Oracle data model and I am posting the first effort on File Storage.

I will update the diagrams as new versions of OpenACS become available(Already obsolete with the release of 4.6.2!)

A year ago, we discussed starting a separate forum for each: http://openacs.org/forums/message-view?message_id=44661
  And an additional forum for marketing and evangelism.

The forums are long overdue. Don B. should have the final descriptions from then for these. If not, you can start with these drafts:

OpenACS End-users Support forum for (nontechnical) end-users. This forum serves managers, business analysts, professionals, and the rest of us who want to ask questions, post ideas and otherwise discuss OpenACS without technical explanations or requiring computer expertise.

OpenACS implementation forum for graphics designers, webmasters, administrators and others who want to install, configure, or manage the operation of existing versions of the OpenACS system. Topics include customizing templates, graphics and other media, running existing scripts, changing default configurations, writing html, dhtml, css, importing data, XML, and creating adp or embedding small TCL scripts in html pages. For improving on the existing system, refer to the developers forums.

It seems to me what you call the "Implementation Forum" would be better named "Deployment Forum". Installation, configuration, template design etc. are all activities that fall within a typical deployment.

The name of the first forum is clear and it distinguishes itself from the other forum in that it is non-technical. Let's explain in the description that it's both for administrators and ordinary users.

Interestingly we were discussing this kind of automatic linking today on the IRC channel. I am finishing up a "trackback" http://www.movabletype.org/docs/mttrackback.html package that will allow any object to be notified when a link is generated to that object.

Documentation pages are indexed as static pages, and forums postings are both objects.

So this is a partial solution. An interesting feature is that this will allow linking to and from off-site content as well.

Joel, here is another reason to have the new forums:

Provide scope in searches. For example, looking for an answer to an admin related question requires going through volumes of developer discussions.  Imagine an end-user trying to find the answer to a question... No matter the choice of terms, they would be statistically unlikely to find their answer.

Why have a separate forum for each documenation area?

Each separate documentation area needs a forum that provides feedback loops to drive revisions.  This is an essential dynamic of content management that cannot be overlooked. Just look at the state of the documentation now (inspite of the heroic efforts by many).

*forums drive documentation revisions*

When people ask questions, they get answered. Documenation maintainers can practically cut and paste relevant info (often quite eloquent) to the appropriate docs (or revise links etc).  This is a very simple "wiki" like process without the complexity of "wiki". The forums can be done now.  With these forums, most anyone could actually do a pretty good job of maintaining the documenation.

I volunteer to convert forum knowledge back to the  documenation. One way to learn a system is to help others with it.

Over the last year, I have been working on docs by combing the forum messages which are full of valuable knowledge (some of it years old). I see how history is constantly repeating itself on OpenACS.org through repetitive discussions.  The OpenACS community has a collective long-term memory problem. The documenation, with the help of these new forums, will help the community learn and grow. period.

I'll address your topics - 'forum to documentation mapping' and 'how many sections'.

FORUM TO DOCUMENTATION MAPPING

I prefer the concept of modifying the forums code to parse out URLs and provide an API that responds with a list of topic_names (not sure if that's the real field) based on a submitted URL. I think the overall approach of forcing forums to carry the load for this is appealing for several reasons:

I thought of it.

It makes it possible to generate a little portlet thing-a-ma-bob that lists 'URLs recently mentioned' so when you come to the site and say, hmm what was that page that Joel mentioned ... you might see it on the homepage or in the history (when you click 'more').

If links rot out you can at least warn people or find out where they have gone (revive the old clickthrough code?)

People are resistant to change. No matter what you do, people will make the most meaningful contributions to the docs, indirectly, in their forum postings. If you (er, someone) implement an API, lets say /forums/who_mentions?URL=http%3A%2F%2Fopenacs.org%2Fdoc%2Fopenacs-4%2Fdb-api.html you will find all threads that discuss, or rather refer to the database API page - not section. This method puts no additional work on anybody - and doesn't treat comments on pages as some special thing that probably few people will use anyway (as shown by looking at comments on the pages right now). So every page in the docs would just have a link to that URL and people can then jump back into the forums from the doc pages.

For instant gratification we forget the above and just put http://openacs.org/search/search?q=http%3A%2F%2Fopenacs.org%2Fdoc%2Fopenacs-4%2Fdb-api.html&x=30&y=8 instead - that way at least you automate a search on references to the page. This approach requires NO code changes - just an auto generated link on each doc page, similar to the way static-comments works now.

People are resistant to change (oh did I already say that? :) There was a thread recently that was griping about how unused all the forums were except Q&A. The likelihood of people remembering to / wanting to add things to yet another module written specifically for the purpose of discussing docs is low. Adding a doc specific forum could work (see below)..

HOW DO WE GET MORE DOCS UPDATED?
Maybe we provide an easy / obvious way to get the docbook source - as in the file repository? Linked to directly from the doc page itself? If we go with a new forum, provide a few links that launch new topics in the 'docs forum' with options including:

Contribute a recipe for xxx
Clarify an error on this page
Random thought about this page

You then create a new thread / post that includes those controlled vocabulary terms in the subject line and includes a link back to the page being discussed. (so you can search for db-api recipe and get a result).

The advantage of this approach is it supports Torben's idea of documentation specific forums by 'generating traffic' in that area and keeping related stuff together.

HOW MANY DOCUMENTATION SECTIONS?

I think you are on the right track - the only piece I see missing is the 1,000 mile high document that describes the various layers the system covers. By that I mean 'what is the relationship between TCL and AOLServer and OpenACS and TCLlib and C code and where exactly are the interpreters (and what are they)' &c.

This got longer than I intended - I might circle back around and give more thought to this final question - how many sections...