Forum OpenACS Q&A: Commenting on the documentation?
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?
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.
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
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.
/doc/user-groups.htmlpages 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.
/doc/news.htmlfile, 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.
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.
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).
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.
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!
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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...</p>
"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!).