Forum OpenACS Development: Re: 4.6.x Documentation; Documentation formatting

Collapse
Posted by Dave Bauer on
https://openacs.org/projects/openacs/doc-project/

We want to coordinate the documentation effort. To do that I started that section to keep track of tasks we needed to complete. You can see that, so far, we have not had much time to work on the list, let alone the actual documentation. Us being myself and Roberto Mello.

I think, although we have a huge amount of documentation, it is quite difficult to learn how it all works together. One problem is that much of the useful documentation for core packages in the the package documentation, while other vital docs are in the Kernel documenation, or "Developer" documenation.

A tutortial such as you propose would replace the developer section with up to date information, and bring in the useful parts of acs-templating, notifications etc.

Collapse
Posted by Joel Aufrecht on
  1. How do I edit that page?
  2. 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.
  3. 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.
Collapse
Posted by Dave Bauer on
Joel,

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.