Forum OpenACS Q&A: Re: Copenhagen - Documentation

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 https://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...