Forum OpenACS Q&A: Re: Copenhagen - Documentation

Collapse
Posted by Joel Aufrecht on
I've started a fresh thread for new forums so that this thread can focus on documentation.

I agree that we need closer integration between forums and documentation. Or rather, between between "places where anybody can post" and documentation. I think what this thread proposes, across several authors, is matching forums and documentation sections, specifically for "User's Guide," "Admin Guide" (including install, I assume), and "Developer's Guide." Is that accurate?

Currently the meat of the core documentation is divided into "Part II. Administrator's Guide" and "Part III. For OpenACS Developers". Then each package has its own documentation, with inconsistent internal structure.

I actually see four divisions, not three, among documentation readers. First, people who want to use some functionality in a web site, without touching any code. They could be end users or end administrators. Second, people who set up and maintain OpenACS sites. Third, people who develop or modify OpenACS packages. Fourth, people who work on core OpenACS. Of course there is overlap between each group, especially between developing new OpenACS packages and working on the core.

(In particular, I think we should make it easier for people to improve the core. When people want features that aren't implemented by the core, we should make it easier for them to implement the new features in backwards-compatible ways that can easily be rolled back into the core, and make it easier for them to contribute the code back.)

So, to continue the discussion, some questions:

Should I work on dividing the core documentation into three or four parts from the current two (I'm not counting the introduction and release notes as a real Part I)? I can see how to divide "Developer's Guide" into "Developing with OpenACS" and "Developing OpenACS." What would go into an end-user section in the core docs?

How do you see the forums integrated with the documentation? I'm envisioning expanding the comments thing - currently it's just an easily overlooked link, and I want to try to turn it into a dynamic page fragment, with an IFRAME or something, so that whenever you look at local documentation you see live comments. That would make it easier for users to respond to docs. But everything would still be per-page - there would be no way to browse or search.

I think it still makes sense to there to be an editorial line between "the docs" and "user-contributed feedback." User-contributed feedback is often more correct and more current than "the docs," but being in the docs means, in the best case, that the information has been tested, is consistent with the community-determined best practices, and doesn't have nasty, undocumented side effects. What can we do to get more docs updated? A central task-list clearing house? (the bug system?) Giving out more cvs access?

Collapse
Posted by Alfred Werner on
Joel - thanks for carrying the torch on this one ...

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...