Home
The Toolkit for Online Communities
17516 Community Members, 0 members online, 2036 visitors today
Log In Register
OpenACS Home : Forums : OpenACS Q&A : New package documentation

Forum OpenACS Q&A: New package documentation

Icon of envelope Request notifications

Collapse
Posted by Lars Pind on
As you all know, we're about to be done with our new workflow package, and it's time to turn the specification (http://www.collaboraid.biz/developer/workflow-spec) into a form useful for developers, as a Package Developer's Guide to Workflow.

How should I go about doing that?

I'm assuming DocBook.

But the documentation should live under packages/workflow/www/doc, no?

How do I make that integrate with the rest of the docbook documentation, or how's that supposed to work?

What's a good example of a well-documented package? (Does one exist?)

Can some of our documentation gurus help point me in the right direction? :)

/Lars

Collapse
Posted by Lars Pind on
One concrete point:

All of the stuff needed for OpenACS docbook stuff seems to be already installed on my Red Hat 8.0 install, except the chunk.xsl stylesheet isn't in /usr/share/sgml/docgook/stylsheet/xsl/nwalsh/html/chunk.xsl. Instead, it's in /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl, which also seems like a more logical place, given that it doesn't have the name of a particular author in there.

Or are there differences that mean I should go out and download the nwalsh version and use that instead?

Also, the tools mentioned on

http://openacs.org/doc/openacs-4/docbook-primer.html

doesn't mention htmldoc, which is required to generate PDF files (which is the default if you simply say 'make' in the packages/acs-core-docs/www/xml directory).

/Lars

Collapse
Posted by Lars Pind on
Still talking just to myself, I find that writing documentation in docbook format distracts way too much from the content, and forces me to put all my effort into the form.

I've found a way out, however, namely W2XML, a thing that can convert Word documents to XML using a specific stylesheet, most notably DocBook.

So now I can use MS Word to write the doc, then convert it to DocBook. Neat. (Thanks, Mark, for the tip.)

Now the problem is that that converter only uses <section> tags, and not the <sect1>, <sect2>, etc., tags, that we tend to use.

Checking the reference at

http://www.docbook.org/tdg/en/html/section.html

it's clear that this should be just as fine. However, using our setup, each section gets the same size header, and the table of contents doesn't work.

Anybody have any idea why that would be and how to fix it?

/Lars

Collapse
Posted by Kurt Martin on
Greetings,

It is very simple to modify the Docbook XSLT in W@XML to make <sect1> vs <section> tags. Simply modify the XSLT. Changing the section tags to sect1 tags is easy. Simply replace the following:

<xsl:template match="h:div[parent::h:body]">
    <section>
      <xsl:apply-templates />
    </section>
</xsl:template>

With:

<xsl:template match="h:div[parent::h:body]">
    <sect1>
      <xsl:apply-templates />
    </sect1>
</xsl:template>

You may have to add a named style in word to pick up nested "sections", and detect this as a class attribute in the exported XML. For example, if you wanted to capture a style named "Heading4ArialNarrow" as your sect2's, then add the following to the Docbook XSLT:

<xsl:template match="h:p[attribute::class = 'Heading4ArialNarrow']">
    <sect2>
      <xsl:apply-templates />
    </sect2>
</xsl:template>

The standard output from W2XML captures each style name and adds it as a class attribute value. It is easy to capture this and modify however you wish.

HTH

Collapse
Posted by Roberto Mello on
As far as I know, each package is supposed to have its own documentation. The index page in /doc scan the installed and uninstalled packages and shows links for their documentation pages, but that's about as far as the integration goes. So package documentation is not integrated with acs-core-docs.

If I were you, writing new documentation, I don't know if I'd go with Docbook. In fact, I've thought about converting our acs-core-docs from Docbook to something else several times (and I was the one encouraging ArsDigita to move the 4.x docs to Docbook way back when).

The reasons are simple... Docbook has all the whiz-bang and cool stuff, and a lot of people use it and all that, but it's just very hard to work with. It is very hard to be able to write a document quickly. There are a bunch of tools to install, a bunch of new, very verbose markup to learn, a bunch of settings to a bunch of places that need to be done.

In short, while it does everything one could imagine for documentation, unless you have someone with lots of Docbook experience/knowledge on board, the cost time-wise to climb that learning curve is so steep that nobody does it because nobody has time to and because documentation teams are seen as third-class citizens in the open source world (meaning you are rewarded for pumping out code, but if you pump out documentation that is seems as a clerical job without importance, so no one wants to get involved too much there).

What ends up happenning is that of the handful of people who are ok with being considered third-class citizens, only a few end up getting the courage to climb that learning curve, resulting in less documents or less updating of documents.

So I've thought about moving our documents to a format that's easier to work with, simpler, less complex, without such a learning curve, so that anyone could contribute docs in an easy manner. One of the formats I've thought of is APT (Almost Plain Text) which Ben Adida told me about a while ago.

http://www.xmlmind.com/aptconvert.html

-Roberto

Collapse
Posted by Talli Somekh on
I started using jEdit for writing docbook docs and was very impressed. It has tag autocompletion, tree views and a bunch of other nice features.

Check that one out, too.

talli

Collapse
Posted by Lars Pind on
Thanks, Roberto. If that's the recommendation, then I'll stick with HTML.

/Lars

Collapse
Posted by Talli Somekh on
Roberto, that APTconvert tool looks pretty cool. It may be a good idea to explore it some more.

Even still, I think we should standardize on Docbook. It can be a pain to start using at first, but once the developer gets used to it is actually quite nice. I know for one of our projects the documentation writer was hesitant at first but by the end he was raving about the combination of Emacs and Docbook for writing a fairly large technical document.

The other day, I got my first taste of Docbook and at first would have agreed with you. I tried doing it by hand, and it was ridiculous. But after some searching, I found some good products and tools, like:

  • jEdit This is a GPL XML editor that is built in Java and totally cross platform. It needs a fairly heavy duty processor (I'm running on a G4 400 and it was a wee bit slow) but it works really nicely. Tag autocompletion, XML tree views, etc. It's a really nice editor. And there are many, many plugins so it has a vibrant community.
  • For OS X: Project Omega has a nice article about using Docbook on OS X. They also released a Docbook-X, a suite of tools to converting Docbook XML to HTML or PDF.
  • For Windows: I haven't used e-notative Docbook Environment (eDE) for Windows because I'm not on a Win box, but they seem pretty comprehensive and I passed them on to a client. I used W2XML to convert a large Word doc to Docbook, and it worked nicely. But it created some really weird and dirty XML, as one might expect, that I had to go through by hand and clean up so that it could be managed and debugged easier.
  • For Linux: I haven't researched this because I haven't needed to, but this Docbook wiki has a fairly comprehensive list of Docbook tools for all platforms.
  • I think that using jEdit plus some command line XSLT transforms is a good suggestion for documentation writers. It may be a bit painful at first, but ultimately I think we would be happier with the result.

    talli

Collapse
Posted by Lars Pind on
What I'd really like to see is a recommendation from our documentation gurus of the exact setup and structure that we should employ when documenting.

Plus recommendations for tools that make it realistic, such as jEdit, make files, whatever.

Plus perhaps pick a package and make that one be documented according to the authorized documeentation standard.

That way we don't all have to spend hours investigating this field. If our documentation gurus could provide the framework, I'm sure more people would be encouraged to contribute. :)

/Lars

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

Collapse
Posted by Jade Rubick on
Whatever we decide on, we need some better documentation on how to do it. Joel is making a really good start, at http://aufrecht.org/openacs-4.6-quick-guide/ch04s02.html

Looking at that documentation, I was even comfortable starting to document in DocBook. I like Roberto's idea better though. Let's make it as easy to use as possible.

I'd even go for a Wiki.

The xsl or whatever translation didn't work for me, but I didn't follow his documentation step by step.

Collapse
Posted by Torben Brosten on
Quite honestly, I think the final test will depend on what actually works instead of what we collectively decide to try. This may seem counter intuitive, but this discussion has been ongoing, in depth, for more than a year. Many decisions have been made, and only those who have taken initiative have provided results.

My own progress has been slow, but I'm working on longer term goals than the immediate documentation needs. Content first, then how to display it. I'll keep everyone posted when it is near publication.

Collapse
Posted by Dave Bauer on
Torben,

Can you let us know which documentation you are working on. It will be better if effort is not duplicated.

Thanks

Collapse
Posted by Torben Brosten on
I'm working on end-user and general admin documentation --as well as how to organize and maintain documentation on this complex system. 98% of it is not original, as I'm harvesting content from the forum discussions.

Sorry if this seems vague. The writing is comprehensive. Were it to be duplicative or redundant and not read, I will be satisfied knowing that I will have gained a much greater understanding of the entire system and the implicit computer science principles that shape its core.

Collapse
Posted by Joel Aufrecht on
I noticed that the "For Administrators" Part of the docs covers only installation, not maintenance.  Could your work fill that gap?
Collapse
Posted by Torben Brosten on
Yes, I'm working on docs for admins. I'm also working  on some of the other efforts that you are currently working on, but don't let that stop you. The results of my work are slow to materialize, because I'm trying to create a "system" that will resolve the repeating documentation/new-admin/marketing issues from a wholistic perspective.  There are definite patterns exhibited in the board messages that can be overcome through more systematic efforts, mainly documentation.  (I believe these are key for OpenACS' growth.)

I'll send documents to you (and the current doc moderators) when they reach working-draft stage.