Follow-up on Pronovix documentation demo

[Jim Campbell <jwcampbell gmail com>]

Hi All,

tldr; there's a web-based documentation project that I want people to test out. 

Yesterday a group that is working on a Drupal-based documentation platform using DITA gave a demo of their project at UDS (DITA is an XML-based doc syntax). I wanted to provide a brief overview of it and see about evaluating it as a team.

Here's the gist of it:

- It uses Drupal forms to allow contributors to enter text into fields that correspond with DITA tags. You don't have to be an expert in the DITA schema to enter text into the DITA fields. This isn't perfect, but has the possibility of opening up ways of allowing for easier community contributions. We could allow contributors to submit content via this tool, and the docs team could do editorial and cleanup work. (It does produce valid markup, though.)

- You can create custom forms to correspond to profiles of your choosing. So you could have forms representing a server profile, desktop help profile with conditional forms for Unity and Gnome Shell, etc. 

- You can upload DITA documents that you've created in a text editor. It will validate them according to the DITA DTD prior to loading, and will not accept invalid docs.

- Once you have the docs in place you can graphically choose the docs that you want to use, and then output them to a wide range of formats.

The cool parts come in with the last part because it allows you to remix the content. Basically, you submit the topic-based documents, and can re-mix them however you want. You can use the mind-map like graphical editor to select just the topics and profiles that you want, and then produce doc output to HTML, ePub, PDF, etc. using just those topics.

You can even allow for community members to create their own documentation "spins" in a way. Someone could create a docs spin for novice Unity users. Someone else could create a docs spin for intermediate gnome-shell users on Fedora. A person preparing documentation for an OEM could create a server-docs spin for Ubuntu Server on AMD64 . . . etc.

This kind of approach can be helpful because it allows you to write a topic once, write it well, and then reuse it everywhere. Using this approach can reduce the amount of content that translators have to translate, too. There would even be the possibility of cross-distro collaboration around a content pool of topics.

A couple of notes. 

- I hadn't seen this project before the demo session yesterday, so this was a bit of a shot in the dark. I had heard about their work on it, knew their hackers were based in Hungary, and thought it would be good to see what their project could do. It obviously has some cool features, but please don't think that I'm proposing this as the most awesome thing evar - I just want for us to see it, evaluate it, and provide feedback.

- The build toolchain isn't in any of our distros (it's packaged in OpenSUSE, but the package is outdated and broken). This is clearly a blocker. Harald Sitter from KDE / Kubuntu thought that this kind of thing wouldn't be acceptable for KDE for about two years because otherwise the tools and toolchain would need to be backported on all of the major distros.

- Integration with workflows is a major consideration. David Planella brought up the issue of gettext-based translations with po and pot files. The Pronovix folks think that they could get that situated with about a day or so's work. That's just one thing, though . . . workflow (esp. with regards to revision control) is a big consideration.

- Hey, what about Mallard? Some of the issues I have with Mallard are that it doesn't allow for explicit ordering of your topics, all of the topics have to be in the same directory (which could be a scaling issue), and (as of now) there are limited outputs - only HTML and rendering in yelp are available. This project can serve as an impetus to address those issues. We can also look to create transforms from Mallard to DITA and vice-versa. There's a lot of momentum around Mallard, though, and I wouldn't want us to throw away the work that we've done.

In all, though, the reason that I'm sending this email is that we've been looking to have web-based documentation tools for a while now, and here's something that's currently in a beta state (they've prepared beta2), and it does a lot of cool documentation stuff. 

The group has set me up with an evaluation environment, and I am pretty sure that I can build sites for people to test things out. I'd like to get feedback from the regular suspects and whoever else wants to give their input - that includes the cool new GNOME documentation interns.

I'll be getting some account info soon and will relay that when I have it.

Thanks, documentation writing people!

Jim