What if wimpy point was used for developing docs, but once they are
released the development continues via tickets in the SDM? I can see the
advantage of wimpy-point for rapid development and collaboration, but I
also see a potential headache if the docs were to stay in there forever.
Having said that, let me digress into the maintenance side of the documentation...
What tools and methods will help OpenACS to have complete, outstanding
documentation?
They will work by...
Empowering the community to easily add value-added information for
consideration for addition in the docs.
Empowering the maintainers of the docs to easily add this info.
The documentation should be easily published in several formats for easy
searching, printing, and referencing.
Without coming up with a new system, I think we can achieve a lot
of the first two items by better integration of the docs with the SDM,
as well as the SDM improvements that Roberto was talking
about today.
I've put in a feature request for the docs to get labeled with version
numbers, as well as more links be added, repeatedly stating that if readers
have suggestions, changes, fixes, etc.-- to head over to the SDM and fill
out a ticket. Since there is only one such link right now, this potentially
will increase the number of suggestions and improvements.
Other Options--
Don't forget that many gave suggestions for improving the docs not
too long ago...
https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0000Tr
https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=0001J2&topic_id=12&topic=OpenACS%204%2e0%20Design
I like the PHP style annotated docs-- but since this would require writing
new software, I'm all for better integrating the SDM and running with that
for documentation maintenance.
I don't think that regular comments should be enabled for the doc pages
as some suggest; the docs are too dynamic of a document. If people are
able to leave comments, then the editor needs to be able to roll these
comments back into the docs (if they are helpful), and then delete the
original comments. This sounds like the SDM to me...
