Forum OpenACS Q&A: Copenhagen - Documentation
Participants
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
- Admin guide (Managing a site)
- Developer'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.
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 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!)
Separate but related thought #1: store those (on and offsite) links in the bookmarks system so they can be tested for linkrot periodically. If they rot out, supply the new place to go, especially if the destination is onsite.
Separate but related thought #2: if a doc gets upgraded to incorporate a thread of conversation from the forums, mark the corresponding forum thread as 'archived' and don't turn it up in searches any more. (Maybe add an option that says 'search ALL threads'. or whatever .. :) That would eliminate the noise since you get a lot of conflicting information sometimes.
A year ago, we discussed starting a separate forum for each: https://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.
I like the two forums that you are proposing and I think we should set them up. Let's allow a day or two for people to discuss the issue first.
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.
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.
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.
- The product needs clear, useful documentation for installing, maintaining, using, modifying, and developing with, and developing.
- Users need an easy feedback mechanism, for reporting documentation problems, missing documentation, requesting explanation, sharing details, etc. Currently we have a bug system, assorted email links, and the forums.
- Documentors need a single point of contact to be alerted to and to coordinate action on all documentation needs.
- We need to lower the bar for people to contribute useful documentation. This includes making docbook easier or replacing it (I favor the former) and also making it easier for users to contribute "blurbs" of unpolished commentary in a place that other users can find them.
- We need users to feel that there is a working documentation infrastructure.
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 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?
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...
