ubuntu-manual team mailing list archive

[Jim Campbell <jwcampbell@xxxxxxxxx>]

Hi All,

I wanted to make a couple of suggestions for the Ubuntu Support and Learning
Center.  For a web-only project, I'd recommend taking a close look at the
Mozilla Sumo project.  The Mozilla instance is available at
http://support.mozilla.com, and the source / build instructions are
available through the wiki: https://wiki.mozilla.org/Support:Sumodev

That is a web-only solution, though.  No outputs to PDF, no desktop manual,
no automated translation tool support (though the site does support
translations).  From some of the discussions from the IRC meeting logs it
sounds like something that you would at least want to look at for feature
ideas, if not using it as a base.

An alternate approach would be more involved, but I think is interesting in
the long-run.  It may be something that would work, given that you noted you
would be looking to get the giant content pool available after the Maverick
release.  It would involve use of DITA, an XML-based syntax that was
designed to create "content pools."  The group may not be so keen on
authoring an XML-based syntax, but the open-source Serna XML editor was just
packaged for Debian Sid, and it allows writers to write w/o having to code
the syntax itself.

The advanced features of DITA are not simple, but I don't think any "content
pool," is going to be easy.  You can skim through this pdf (
http://www.marklogic-news.com/images/MarkLogic_Flatirons_07_Using_DITA.pdf )
to get a long-range picture of what DITA could allow you to do, though.

Put succinctly, DITA content is made up of topic chunks, roughly split out
into "concepts," (what is Ubuntu, and how is it different from Kubuntu and
Xubuntu?), "tasks" (How do I set up a VPN connection?), and reference topics
(typically command syntax examples, programming instructions, and other
reference material - would be good for server-related content.).  DITA Maps
are used to string all of the content together - you can use the maps to
cherry-pick from the content pool, and put some topics together for a
quick-start guide, some for a manual, some for server docs, etc.

As a note, DITA can output to pdf, html, epub, docbook, and other formats.
(Shaun McCance from the Gnome doc team presented to the DITA help committee,
and they even said they would look to produce Mallard output from DITA
content.)  OpenSUSE is the only distro that currently packages DITA.  I'll
say again that it is not a simple syntax, and even using the editor is not
super-simple.  I think that creating content pools will require thought and
planning initially, but will pay off for Ubuntu documentation in the
long-run.

Here's the wikipedia page for this.
http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

Sorry if this is really long, but I wanted to get these things out there
before things got too finalized.  I hope this is helpful!

Jim