What's the best way to get community feedback on doc work in progress? I can keep posting one-offs on my site; I can check stuff into cvs and invite people to look at them through the cvs web interface (e.g., tutorial.html. (I can never find the cvs interface without searching - could this be linked from somewhere prominent like https://openacs.org/projects/openacs/?) A third way would be for me to maintain a HEAD or pre-checkin instance of the doc package on one of my servers. I'd like to post work-in-progress as soon as it's specific enough that people can see where I'm headed, and before I've gone too far in a direction that people disagree with.
My lists of planned work are ... mostly already detailed in this thread, actually. Here's current status:
Add an Upgrade section (already checked in to cvs)
Revise the Install Section to:
Include most current docs on non-linux installs (started, needs volunteers with those platforms)
Include a Reference Install (started; needs community feedback on what a Reference Install should be)
Integrate all the supporting software into the flow (not started)
Add a maintenance section (not started)
Rearrange the Developer Documentation: (in planning)
First, a hello world tutorial (like this but shorter)
Second, an extended tutorial with standalone sections for each of the topics detailed above
Third, the existing material, updated and cleaned up. The difference between the extended tutorial and the current developer's guide is that a tutorial is oriented for learning and the guide is more oriented towards reference. Where possible, I'd even like to consider moving material from the Developer's Guide to the per-package documentation.
I am not sure where the documents in progress should go. CVS probably would be a good place.
I have given you admin privilege over the documentation project page.https://openacs.org/projects/openacs/doc-project/ If you visit that page, you will see an Edit This Page link at the botton. You can add additional pages as necessary.