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
