Forum OpenACS Q&A: Commenting on the documentation?

Posted by Gregory McMullan on 08/18/00 06:56 PM

I'm finally getting a working OpenACS system up and running (life got
interesting - surprise!), and finding some things to suggest in the
documentation. So, I go to the documentation section of the site
(great work on the docs, Roberto!), expecting to be able to comment on
the pages right there, but I didn't see a "comment on this page" link
as I've seen elsewhere. Is this something that other people think
would be a good thing to have? Or was I being blind and it was there
all the time?

2: Response to Commenting on the documentation? (response to 1)

Posted by Ben Adida on 08/20/00 12:21 AM

I'm open to that, but not inline, so there would be a link to another page with comments on it. Anyone else want to voice an opinion on this?

3: Response to Commenting on the documentation? (response to 1)

Posted by Don Baccus on 08/20/00 01:58 AM

Well ... there's an SDM package for the docs, any reason not to just ask folks to use that for suggestions? Set it up to automatically assign them to Roberto and wave his ever-growing todo list in his face whenever he visits openacs.org :)

4: Response to Commenting on the documentation? (response to 1)

Posted by Michael Feldstein on 08/20/00 03:08 AM

I see comments on docs and the SDM serving two different purposes. The SDM is specifically intended for reporting problems. Comments on docs could include stuff like tips, tricks, and gotchas to watch out for.

5: Response to Commenting on the documentation? (response to 1)

Posted by Gregory McMullan on 08/20/00 03:42 AM

I had been picturing it like the "Readers' comments" on many ACS pages (e.g. the big batch on "Why Not MySQL"), though I hadn't worked through the issue of what happens when suggestions for changes get migrated into the newer release of the documentation. I do also like the idea of a list of tips or gotchas to keep in mind (like "if you are installing the current (as of now) OpenACS, you probably want to disable pulldown menus, because they seem to be busted and break non-intuitively (at least for me starting out)". In a way, the things that prompted me to comment do count as "Bugs against the docs" and thus fodder for SDM, true.

6: Response to Commenting on the documentation? (response to 1)

Posted by Don Baccus on 08/20/00 03:47 AM

Mostly I don't want to end up with a bunch of useful stuff buried in comments here at openacs.org, that don't end up in the docs - because someone in dire straights may be off working on a laptop or whatever without 'net access. They want the goodies in THEIR copy of the on-line docs.

I'm a bit worried that using comments for reporting what in essence are doc bugs will just increase the load on the maintainer, which also increases the odds of useful stuff being missed when it is time to upgrade the docs.

7: Response to Commenting on the documentation? (response to 1)

Posted by Roberto Mello on 08/21/00 02:47 AM

Sorry about not replying earlier. Greg, that's a good point, but I agree with Don.

I like things on the docs better than just online. I've been asking people to submit comments and bug reports/feature requests on the SDM. That way it shows on my TODO list. However the vast majority of reports I've received were through e-mail. Maybe a "Documentation Bug Reports / Feature Requests Here" on the homepage would help?

I hope Ben finds sometime to delete the "old" packages (or mako them owned by me) so that only the current set of docs are showing as packages 😊

8: Please allow comments on openacs.org/doc files --> current method unwieldy (response to 1)

Posted by Carl Coryell-Martin on 07/10/01 01:10 AM

Summary: The stock module documentation SUCKS, and it's hard to improve. Supporting comments on /doc will help us improve our documentation quickly, and put it where people could find it.

Attention Conservation Notice: Long rant about lack of openACS documentation, with criticsm of current methods for collecting community feedback and suggestion for work that someone else could do to make it better.

Okay, for the second time in two weeks I have been mucking around in the openacs source code and had a serious AHA event, that I thought really really needed to be documented and shared.

Right now there is no satisfactory way for me to do that.

My options appear to be:

go into Sourceforge and change the doc files myself.
- nice because will get into cvs tree immediately
- ugly because I haven't made any updates lately and I might be stepping on toes.
- ugly because everyone might be helped by the new comment and they won't get to see it until: they download the newest version, openacs.org upgrades and my changes show up on the live site.
Submit patches and tickets in the SDM. (this is what I did last time.
- Nice because it makes it easy for the change to go through proper channels
- Ugly for all the above reasons, only more so. And who is going to browse the SDM looking for hints on how to use the news module.
Post a comment on the BBoard. possible helpful since people surf the bboard all the time, and often search it when they have questions. Lame because it doesn't get into the distributions withought extra effort on someones part.

I would really like it if I could post a comment on the bottom of the /doc/news.html or /doc/user-groups.html pages and know that:

people browsing the documentation online would find it.
When a new release happened the best comments would be rolled into the documentation.

Last week I realized what the various default newsgroups were in the News module and how they were designed to be used. Thats great, I have been using the news module for a year, read both Philip's books and all the docs and I didn't figure it out until last week. Since I like to think of myself as reasonable up on the ACS and I had trouble, I thought others might also. I ended up patching the .sql file and the /doc/news.html file, submitting a ticket in the sdm and posting my patch. It was a ton of work and only the most dedicated is likely to do that, furthermore, its likely to be months before anyone else notices.

Today I figured out some nifty undocumented features of the user-groups facility that I would like to share with the world. I don't really want to write up a full page document outlining how to use this wizzyness, I just want to draft a paragraph hint suggesting how to use it. (just so you know, the ug_serve_group_pages proc appears to respect the has_virtual_directory_p property of group_types even though there is no pages that manipulate that property.)

to conclude: comments on documentation seems like a logical place to share experiences with the existing documentation and serve as jumping off points for updating the docs.

Cheers,

Carl C-M

9: Response to Commenting on the documentation? (response to 1)

Posted by Don Baccus on 07/10/01 02:07 AM

Well, if you've been following events here, you'll have noticed that the kind folks at Musea Technology have offered their services to help
improve this site. This will include a fair chunk of programming services.

Ben and Musea are asking for input, and of course a hot item is the whole issue of collecting documentation improvements from our user base.

The biggest problem with the openacs site can be found in your statement regarding "criticism of the current methods for collecting community feedback and SUGGESTION FOR WORK THAT SOMEONE ELSE COULD DO TO MAKE IT BETTER."

Pardon me for being nothing but a humble, unpaid volunteer who can only spare a dozen or so hours a week on the OpenACS project, but suggestions for work that SOMEONE ELSE CAN DO, while satifying to the person making the request, in many cases will lead to a suggestion of work that will NEVER get done.

The Musea folk have offered an alternative - along with suggestions they're offering a bunch of their time to implement them.

Along with some time to implement suggestions made by those like you who apparently hope that someone else will implement them.

I realize that you folks at Civilution are very busy with client work
at the moment, but still ... I have to admit to being a bit tired of folks demanding improvements in the website or overall project management without offering to dig in and help out. If I weren't busy with client work myself I would be digging in and hacking improvements
into the website right now.

Let's all work with Ben and Musea in order to take proper advantage of
Musea's offer to supply some hacking muscle for us to apply to the design and functionality of openacs.org.

10: Response to Commenting on the documentation? (response to 1)

Posted by Carl Coryell-Martin on 07/10/01 02:57 AM

Don, well I never thought it would happen to me, but I think I have been bitten by the low bandwidth of this forum, and I apologize.

Mea Culpa: My Attention Conservation Notice which included the phrase "and suggestion for work that someone else could do to make it better." was intended to be somewhat tounge in cheek: IE don't bother reading this notice unless you are willing to put up with the aforementioned. (This is a tick I picked up from hanging out on the Viridian Mailing List).

So let me add in my defense:

I tried to outline the various different ways of sharing my hard lessons and why they felt dissatisfactory.
I tried to suggest a simple change that I didn't have the power to make that could address many of my concerns.
I did attempt to review the current discussion on the topic.

Finally, I would happily take some responsibility for some of the module documentation and roll comments made by others into the core distribution. I did that for news (see this patch and ticket) and I am working on that for user-groups (my own comments and anyones that I can find on the bboard).

Cheers,

Carl C-M

11: Lowering barriers to participation (response to 1)

Posted by Jonathan Marsden on 07/10/01 12:36 PM

I think this issue is about lowering the perceived barriers to taking part in the OpenACS project. It is 'easy' to post messages on a bboard, so lots of people do that. It is 'hard' to create patches and submit them to the SDM, so far fewer people do that.

While allowing comments against files under /doc makes life 'easier' for those wanting to comment on docs (!), it could result in those useful comments not being integrated back into the underlying docs for some time. However, without such a facility, those comments may simply stay in the head of whoever is thinking them, which is worse still!

I edited and submitted patches against some of Roberto's docs, a while back, but for some folks, that process would have been "too hard", and they would have given up. The barrier is too high.

So, I'd say that allowing GC-style commenting on docs is likely to be a net gain for the community overall, because it will encourage more people to participate in trying to improve OpenACS. Maybe Roberto (or someone Roberto persuades to do this for him for particular documents or modules?) could try to allocate an evening every month to go through the resulting comments and incorporate them back into the base documentation they refer to?
Can we try it? If in three or four months it is clearly not working (no comments make their way back into the docs, or noone actually
comments anyway!), fine, we'll know we need to find a better way.
But at least we will have tried.

12: Response to Commenting on the documentation? (response to 1)

Posted by Don Baccus on 07/10/01 09:25 PM

Roberto's working on getting general comments enabled for documents at openacs.org. Again, this isn't a matter of philosophy, etc but simply
one of people having time to implement needed changes. If you've played with the static content code in OpenACS 3.2.5 you already know that setting it up to work with content on your site takes a bit more effort than simply changing a "0" to "1" in your .tcl init file. Not a hell of a lot of work, but greater than zero work.

Carl - the tongue-in-cheek nature of your comment wasn't at all obvious, at least to me. Now that you point it out I can re-read it and see the attempt at humor, but it certainly escaped my notice yesterday when I first read it!

13: Golden mean? (response to 1)

Posted by Andrei Popov on 07/10/01 09:54 PM

If it reads like a rant, it must be a rant, right?
I think it would be impossible to find a "golden mean" here. Maintaining a full documentation set means that there is a person responsible for making sure it is current (i.e. matches the software it talks about), correct (both gramatically and technically) and covers all the important (from user point) items.
You cannot have good documentation unless you have a central point of maintenance (which does not necessarily mean dictatorship). You cannot have central point of maintenance if document content is scaterred between static .html files on a web server, DocBook .sgml files on a harddrive of a maintainer/in CVS and user comments in the database. You cannot have easy collabaration if you are going to have to make users download DocBook sources, install Emacs and PSGML, learn to use diff and patch, etc.
What gives?
I guess one could move through little trade-offs: allow (not in-line) GC in /doc. Add "Get latest copy from CVS" link on a doc page for registered users, or "I want to comment/correct this". Allow this only for registered users.
Another option is covered in WP -- IIRC you can have it in a "shared" mode, i.e. a presentation can be allowed for editing by others.
How about the manuals module mentioned elsewhere on this site? It may not be great, but it may be a step to a more coloborative documentation creation...

14: Response to Commenting on the documentation? (response to 1)

Posted by Roberto Mello on 07/10/01 10:46 PM

Andrei,

"Maintaining a full documentation set means that there is a person responsible for making sure it is current(...)"

I'd much rather have a small group of people maintaining the docs, then one person.

"You cannot have central point of maintenance if document content is scaterred between static .html files on a web server, DocBook .sgml files on a harddrive of a maintainer/in CVS and user comments in the database."

You either don't understand how the documentation is authored or you worded your phrase poorly. The HTML is simply an output of the SGML sources. Those sources are available in one central location for anyone to pick and change.

"You cannot have easy collabaration if you are going to have to make users download DocBook sources, install Emacs and PSGML, learn to use diff and patch, etc."

I never told ANYONE "I'll only accept changes to the docs if you send me a DocBook patch". Dozens of folks have sent me things that needed to be changed/improved in the docs through simple e-mail ("There's a typo on section x of doc y"), through SDM submissions in either the form of patches or bug reports much in the way of the e-mail type I just mentioned. Just check the "Acknowledgements" section of each of our docs.

So it's incorrect of you to say that we make users install all the software you mentioned and learn how to use it. If everyone sent me DocBook patches, that'd be awesome, but I'm not picky. Whatever is sent I accept.

I admit that this is not the greatest way of doing things, but it works. For collaboration, we are allowing comments on the /doc section of openacs.org and I'll monitor those. Deleting things that are not relevant or that have been moved to the doc sources.

A manuals module? Great, if you can solve the problem of outputting to different formats and quality assurance better than what we have now, I'll be very happy to see it implemented (hint, hint!).

15: Response to Commenting on the documentation? (response to 1)

Posted by Carl Coryell-Martin on 07/10/01 11:48 PM

Well, as soon as /doc accepts comments, I'll add my notes on news and user-groups.