Forum OpenACS Q&A: Response to Documentation Update (IMPORTANT)

Collapse
Posted by Roberto Mello on
I recommend that we have the canonical version that Vinod has written as the primary install guide and then offer various other install guides for each OS and each Linux distro.

That's what I had in mind when I put different items for BSD and Windows. There's obviously interest from the comunnity in these pieces of documentation.

However, I fear that things can get out of hand and outdated. I was involved for a while with the Portuguese-HOWTO (Linux) and it was a nightmare to keep so many different "subversions" for the different distros under the howto. So I think we should label the maintainers and dates those specific portions (which would be representated as chapters) of the guides were last updated.

What does the ACS Core Docs consist of actually? Does this item represent all of the packages in the system? Do we need to find volunteers to maintain the docs for each package and/or module?

The Core docs consist of the Kernel documentation, install guide, docbook-primer, engineering standards, etc. Besides the core docs, each non-kernel package has its own documentation, and I think that the person responsible for porting that package should be the one that makes any corrections before our first release. There shouldn't be many done, except for some packages that had lots of changes (CMS?).

The Query Dispatcher doc, Object System doc and the Permissions doc are all fairly hairy pieces of literature, right? What kind of documentation needs to be written, and who will the intended audience of these pieces be?

Not necessarily "hairy". The Query Dispatcher is fairly simple for example. We just need to explain how it works and its API.

As for the Object and Permissions System, these get a little more tricky, and those with experience with these systems would be the most apt for the job.

Every piece of documentation on OpenACS (for the most part) currently has three types of docs: For Everyone, For Admins, For Developers. I think we should continue with these three audiences.

I assume that you mean that they are too superficial since you ask for more detail and examples, but it may be important to write at least part of the docs for beginner's. Is this right?

The current and permissions systems documentation is hard to understand. The examples are too shallow and minimal and often you think you understood how they work, but 5 minutes afterward you realize you really don't.

Documentation for these systems must be easy to understand and follow. I wouldn't label them "for beginners" because that carries too many implications. I'd just say that they need to be improved so they are esaier to unsderstand and follow.

Perhaps we should put this item (Beginners' Guide) on the fast track as well?

I didn't put the beginners' guide on the critical path because it's not absolutely necessary to have it before release. It would great to have it, but I didn't want to tie our first release upon it. However, I'd love to see us have a release with that guide included.

I think that it might be a good idea to define a certain style for the docs.

The documentation included with the ACS didn't really follow this in all packages, but I like the "For Everyone, For Admins, For Developers" division. Since OpenACS is composed of lots of little packages, I think it would be fairly easy for new packages to follow this convention.

Your list of items is good too, but would need to be split into the three categories. For example what you call "Exec Summary" would be the "For Everyone" section. The other 4 would be part of "For Admins" and then the design and API would be described in the "For Developers" section.

How about the ACS Service Contract stuff?

What about it? Do we need/want more/better documentation for it? Is there a special documentation need for the Service Contract that I'm not aware of?