Forum OpenACS Q&A: Documentation Update (IMPORTANT)

Collapse
Posted by Roberto Mello on
Here are the news from the Documentation front:

I decided to follow Don's "status page" model and created a documentation Status page. It lists the things that need to get done, who's assigned to those tasks, which tasks don't have anyone assigned, critical path, etc. It is at https://openacs.org/new-file-storage/one-file?file_id=270.

Everybody that is interested in contributing to the documentation effort in any way should take a look at that document. I've received e-mail from several people wanting to contribute to documentation (thank you). Please look in that document, find something(s) you'd like to work on and e-mail me. If I don't get an e-mail from those that have already e-mail'ed me, I will be e-mailing you 😊

I also uploaded an OpenACS Documentation Guide that basically contains everything you need to work with OpenACS 4.x documentation (let me know if I'm missing something). This is the HTML generated from one of our .xml files on CVS. It's at https://openacs.org/new-file-storage/one-file?file_id=271

And also I uploaded the HTML for the Intro to Emacs PSGML that is part of our documentation. It's at https://openacs.org/new-file-storage/one-file?file_id=272.

Sorry this took a long time to get out. It took some banging my head on the wall to find the best way to go about this, plus some other things that happenned these past months got in the way.

Commenting is enabled in all these docs, so don't hesitate to fire away. There are lots of things to do in the documentation, and you can write, edit or proofread documents, so there should be jobs for everybody interested.

I filled some of "Writer" columns in the Status report document with names with question marks. These are the most likely people to take over that task because they've showed interest in it, or had already written it. An example would be the BSD installation guide, where I put "GilbertW? WalterM?" suggesting Gilbert Wong or Walter McGinnis, because they've already written the FreeBSD and Mac OS X install guides.

I have an item of documentation there called "Beginners' Guide". This is for those that have wanted a "non-techie" introductory sort of manual (which I think is great). Also an item to port the ACS 4.x psets.

Hopefully this will bring good cheers to the OpenACS community. Thanks to Talli and Don for constantly pushing me 😉 Now let's get these things written already!

Collapse
Posted by Talli Somekh on
Thanks for the update Roberto. Here are some of my initial thoughts.

  • I agree with your decisions on which of the items deserve critical path consideration. I think that it's also clear that the Installation Guide and the ACS Core Docs items are the most important since those are the only projects that have writers now.

  • For the Installation Guide, from what Vinod has written so far it seems that his work is based on Debian, right? That's fine. I guess that can be the more or less canonical guide for installing the OACS. However, there is a bit of a difference in configuring the various Linux distros, not to mention the differences between installing it on the BSDs and on Windows.

    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. So the layout would be:

    • Vinod's Canonical Install Guide (Debian Linux?)
      • Linux
        • Redhat 7.x
        • Redhat 6.x
        • Suse
        • Slackware
      • Windows
        • Win2K
        • WinXP
      • Gilbert Wong's FreeBSD Guide as the canonical guide for BSD
        • OpenBSD
        • NetBSD
      • Walter McGinnis' MacOS X Install Guide

  • 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 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?

    I think that these are pretty critical to cover. When you say that the Object System docs and the Permissions docs are to simplistic, do you mean that they were written for beginner's or that they are too superficial? 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?

  • Since the Beginner's Guide is already being written to a degree (I know that David Geilhufe is surely doing it, and perhaps Tapiwa is adding some pieces as well) perhaps we should put this item on the fast track as well?

  • I think that it might be a good idea to define a certain style for the docs. What I am referring to is not necessarily the style definitions described in the XML or SGML Docbook sources, but how to word certain things and what items need to be included in a "complete" piece of documentatoin.

    For instance, I think that a complete piece of documentation for a package would include:

    • Exec Summary or Introduction This would be a short introduction to what the package is, what it does, where it should be installed, etc. Just a summary of what is to come. Somewhat like the "Big Picture" piece of previous ACS docs, but more complete. In fact, I like the way Neophytos and Kapil called this section "A Hitchhikers Guide to ..." in the docs they wrote for the ACS Service Contract.
    • How to install This could very well consist of "Go here and download the APM" but it should include whatever the process is.
    • How to configure What files need to be configured, where the files are, what possible problems need to be looked for, etc.
    • How it works A description of the guts of the application, package or module.
    • Troubleshooting tips This item could be implemented in a couple of different ways, from general comments to a Wiki-esque app using ETP or Jerry Asher's wiki application. Basically, it should be a page where people can add their experiences of fixing or troubleshooting applications, packages or modules. It should also provide a way to link to appropriate bboard threads where the package was discussed.

  • How about the ACS Service Contract stuff? I understand that it is becoming an important piece of the system, and will continue to be so if for no other reason than OpenFTS uses it. I know that Neophytos and Kapil have written something up very quickly that solves most of the problem. I also understand that OpenForce used the ACS-SC pretty heavily in dotLRN.
Those are some of my initial ideas. What do you (and others) think?

talli

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?

Collapse
Posted by Don Baccus on
I like the "For Everyone, For Admins, For Developers" split, too - maybe because I've been spending time with the Workflow docs (which follow that form).

Service Contract - the existing .txt doc is a bit sketchy so needs fleshing out, needs to be formatted in XML, etc.  I don't think it needs anything more detailed than, say, the Workflow docs (which themselves need more detail, there are features not documented anywhere but the code at the moment).

Hmmm...we really do need some "For Users" docs, too.  Workflow, for instance, could use some better docs for users (as more packages make good use of workflow the central UI there becomes more and more important and ought to be documented).

But for this release ... my personal goals are very modest.  For beta even more so.

Collapse
Posted by Talli Somekh on
Roberto wrote: "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. "

Yes, that's precisely what I meant. That each OS gets a sub-chapter of the Install chapter and each distro perhaps gets a sub-sub-chapter.

Roberto wrote: "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."

OK, this is a very good convention to follow. I agree that your suggestion maps to my points as well.

Don Baccus wrote: But for this release ... my personal goals are very modest. For beta even more so.

I agree with this too. I assume we'll more or less be releasing the aD docs with edits and and small fixes. But from the versions on those docs are .1, .2, etc. So I hope that they are complete but those numbers sort of lead me to believe otherwise, especially since now the system works in PG as well.

I also think it's important to have a way to attach important bboard threads, comments or other things to each doc associated with a package, module or app. I'm mostly thinking about how to design docs.openacs.org so that a crude "knowledge management" system, if I can use that term, can be made so searches for fixes, bugs or info becomes easier.

talli

Collapse
Posted by Torben Brosten on
Hi Robert, thanks for creating the doc status.

There needs to be some kind of jargon register also..

Something to help people find the context of what others are discussing in the forums, so they can seek answers on their own. And, a place where this community can refer to for common meanings within the OACS environment.