Forum OpenACS Q&A: Please allow comments on openacs.org/doc files --> current method unwieldy
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.