Forum OpenACS Q&A: Community Documentation Using Wimpy Point

Collapse
1: Community Documentation Using Wimpy Point
Posted by Tom Mizukami on 05/10/01 12:19 AM
I would like to float the idea of using Wimpy point to make our documentation more community based. I have cut and pasted Roberto's installation guide into a wimpy point presentation.

If I could list all registered users as collaborators then everyone could add and view comments as well as edit the slides using the display-edit view. I have added this as a feature request in the SDM.

I think this has some advantages over using a Wiki, primarily being able to save versions to protect the base documentation from malicious editing and being to reuse content in other presentations.

As a tangent does anyone know how to upload a background image.

Collapse
2: Response to Community Documentation Using Wimpy Point (response to 1)
Posted by Don Baccus on 05/10/01 12:38 AM
I'm a step ahead of you, dude :)

I wrote a wimpy point presentation outlining the steps involved in
porting an OpenACS 4 package to Postgres, for our hordes of
eager-beaver volunteer's enjoyment (mostly to help them avoid some of
the traps I've fallen into thus far).

The only problem with using wimpy point is that these presentations
are only available on-site, and won't get into the documentation.

However ... the wimpy point module generates HTML.  It shouldn't be
all that difficult to get it to generate the SGML or XML used by the
OpenACS 4 documents or Roberto's OpenACS 3.2 docs.  Then we could have
sorta the best of both worlds - the online advantages of a wimpy point
presentation and the option, if we wished, to publish one as part of
our docs, along with comments.

So I'm personally in favor of using wimpy point as a tool.

Collapse
3: Response to Community Documentation Using Wimpy Point (response to 1)
Posted by Roberto Mello on 05/10/01 01:09 AM
WimpyPoint generating SGML... that's an interesting thought. Indeed we'd have the best of both worlds. As Scott Goodwin noted on a thread on the OpenNSD founders list, a few regexp's should generate SGML from HTML, but the tricky part is getting the links all setup.

Also, I am not sure how to make that scalable to larger docs.

Collapse
4: Wimpy for documentation development; SDM for Documentation Maintenance? (response to 1)
Posted by Sam Snow on 05/10/01 05:32 AM
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...
     

    Collapse
    5: Response to Community Documentation Using Wimpy Point (response to 1)
    Posted by Don Baccus on 05/11/01 02:06 AM
    I think Sam's maybe on to something.  I originally thought to use
    wimpy point as a quick and easy way to build documentation for us to
    use ourselves, i.e. dynamic stuff that probably would never be
    "published".

    Then I thought about generating SGML to feed to docbooks...and Tom
    started this thread.

    This dynamic, quick and easy approach probably does decay once
    things stabilize, as Sam suggests.  Hmmm...

    Collapse
    6: Response to Community Documentation Using Wimpy Point (response to 1)
    Posted by Tom Mizukami on 05/11/01 02:44 AM
    With a couple of minor hacks (ok, I don't know how minor) I think wimpy point would be a great tool for collaborative documentation. As I mentioned above we would need to be able to add all registered users as collaborators on a presentation and incorporate the HTML for printing as on the aD site.

    The SGML and/or XML output is an interesting idea. I not sure about the SDM because you can't view the SDM entries in-line with the documentation. I was suggesting using and distributing the WP documentation in place of the current static html not in parallel.

    Sam is right in that docs SHOULD be dynamic, however, it has been my experience that they decay because they are not dynamic enough. Somebody loses entheusiasm (not Roberto) or gets too busy and the docs fall behind the curve. This was certainly the case with some of the aD docs not keeping up with file locations, Oracle version, etc.

    It only took me a few minutes to cut and paste Roberto's html into WP. For very little effort we can add a collaborative element to our documentation in what I think is the most usable form; comments on an item directly below the item.

    Collapse
    7: Response to Community Documentation Using Wimpy Point (response to 1)
    Posted by Roberto Mello on 05/11/01 04:34 AM
    It's awesome to see people interested in improving our documentation!
    I sure hope we can continue this effort. Writing the 3.x documentation
    was pretty much a lonely job as the community was small, but now that
    the community grew (and the ACS Tcl community "moved" to OpenACS) I am
    psyched to see this level of interest, not only in documentation, but
    the whole system!

    My worry on letting the documentation being dynamic is the quality.
    It'd be hard for me to keep revisiting the docs if they were
    world-writable (e.g. Wiki) and keep track of who and what was changed,
    then rollback bad changes. I don't want to do that. If someone is
    really interested in contributing a piece for the docs, I don't see
    how writing a text file and sending to the person in charge can be
    that hard.

    There are bugs in docs, just like software, but unlike software (at
    least web apps where you can just fix a file) it's harder to patch
    because you have to regenerate it, etc.

    Now, for quickly building documentation that doesn't yet exist, then
    it can be a good thing, as long as someone lays out an outline of
    what's to be written (e.g. slides in a Wimpy presentation).

    As for current docs, adding a comments feature like PHP's or
    postgresql.org/idocs should be pretty easy either using the general
    comments module or a slightly modified version of the same.

    BUT, if, when a person suggests a modification to the docs, that would
    actually cause a ticket with a diff generated on the fly to be
    submitted to the SDM, now THAT would be cool. Because then I could
    easily track who and what the modification is. What do people think?
    If somebody would like to code this up (and it should be fairly
    simple), go for it! :)