Forum OpenACS Q&A: Re: Copenhagen - Documentation

I agree but also disagree. (And I'm not picking on YOUR idea). Adding additional forums will not solve the fundamental disconnect between documenation and discussion areas.

I think there is an core group of developers to whom everything is obvious. There is a significantly larger group of people who have no idea which suggestions are actually relevant.

In a system where there is ACS, ACS Java, Oacs 3.x .. 4.x you find a lot of conflicting information. Ideas that applied to early stuff is obsolete.

Using the forums as they exist can be frustrating - there is no clear sense as to what order results are being returned - is it by date? When I see two answers to a question I can't tell which is newer. It's not message_id as you can quickly tell when you run a search. Returning the link to the exact post rather than the thread can also be overwhelming because terms are often repeated throughout the thread so you get (e.g.) 4 matches per thread rather than the whole thread which means you get a lot of results to wade through.

Lars pointed out a great article - http://www.openp2p.com/pub/a/p2p/2003/01/07/lazyweb.html in his blog .. it feels to me like the community is set in its ways about how to solve the documentation problem (just rewrite everything again) rather than try to understand the dynamics of a community system over time. There WILL be linkrot. There WILL be information that is not addressed by documentation, no matter how thoughtfully and carefully it is written. There will be postings in the forums whose value is assymptotic to zero in a short order of time.

I think rather than proposing ONLY a different place to do things the same way, we need to take the fundamental step of trying to link discrete sections of the openacs site - a large percentage of what is discussed in forums is either already addressed in the documentation, or points out that the author assumed too much knowledge on the reader's part to begin with, or just didn't fully understand how to explain something. One of the coolest things that makes people like openacs as a platform is that all the components seem magically aware of each other. Documentation feels like a dead end, rather than a living breathing wiki-ish place to describe how to do stuff.

From the documentation side there is a comments option - I assume that is provided by the static-pages system. The problem is that very few people bother using that at all. Better, much better, would be to extract URLs from the forum postings and if they point to a page in the documentation you provide a backlink to that thread from that doc page. You create the habit of mind of relating discussions to documenation topics, where appropriate, and you can navigate to and fro.