Forum OpenACS Q&A: Re: New package documentation

Collapse
Posted by Walter McGinnis on

I've often wondered why we haven't made Wimpy Point our documentation standard. Obviously it lacks some key features and its a pain to write in HTML forms, but the gains could be great and it shouldn't be that hard to extend for our uses.

Here's an off-the-cuff idea of how it might work:

  • openacs.org has a canonical location for each package's documentation which is an instance of the wimpy point (WP from here on) package, comments turned on
  • if it doesn't already, WP should use the CR so that it has versioning
  • WP should be extended to output several formats (HTML is easy, PDF, DocBook, or whatever) of an entire presentation (with or without comments, might be nice)
  • when release time comes around for the package, mark the version of the documentation for that release and export in a convenient format
  • add an import feature, so that people that don't want to copy and paste to html forms can write in emacs or whatever (surpise, surprise, I vote for being able to import the new Keynote XML format)
  • add an "import/apply style sheet" to WP if it doesn't already have it

From where I stand the main benifit of DocBook is its automatic creation of navigation. Big deal. WP has a pretty straight forward interface for creating navigation. WP, provides an interface for multiple authors to work from the same place while maintaining version control and allowing comments. It has a low learning curve and is put together in a way that non-geeks can grok.

Last time I checked, we were developers of dynamic database backed websites. Let's eat our own dogfood.

Collapse
Posted by Walter McGinnis on
Here's a follow up to my rant about WP supporting import via Keynote's XML features:

http://www.macdevcenter.com/pub/a/mac/2003/11/18/keynote.html

Pretty basic stuff, but I still like the idea of wimpy point being able to slurp up XML versions of presentations.  Interestingly, if we add export to Keynote, a user could then use Keynote to export the WP presentation to Powerpoint.

OmniOutliner has numerous export options as well:

http://www.macdevcenter.com/pub/a/mac/2003/12/12/omnioutliner.html?page=2