ubuntu-manual team mailing list archive

[Ilya Haykinson <haykinson@xxxxxxxxx>]

Jim,

Thanks for examining these two formats. I don't have a lot of love for Sumo,
mainly because of its limited adoption but also because it seems to be
targeted at the specific process at support.mozilla.com and not much else.

DITA, on the other hand, looks pretty fully functional. We've prototyped a
section of our manual in DocBook, and it seems to fit our needs quite well
in terms of richness of markup. That said, DITA appears to be a fairly
comprehensive markup language as well -- the two appear to have a lot of
parallels, too. See
http://www.slideshare.net/day/doc-book-vs-dita-teresa<http://www.slideshare.net/day/doc-book-vs-dita-teresa?from=ss_embed>
for
an example.

As for editing support etc, I think that our goal is to develop enough
software so that authoring does not need to happen via external editors --
instead, the superstructure will be provided by code, and only individual
content units will need to be authored by individual contributors. This
would make the specific complexities of some of the formats somewhat moot.

-ilya haykinson

On Sat, Jun 12, 2010 at 6:13 PM, Jim Campbell <jwcampbell@xxxxxxxxx> wrote:

> 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
>
> _______________________________________________
> Mailing list: https://launchpad.net/~ubuntu-manual
> Post to     : ubuntu-manual@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~ubuntu-manual
> More help   : https://help.launchpad.net/ListHelp
>
>