ubuntu-manual team mailing list archive

[Jim Campbell <jwcampbell@xxxxxxxxx>]

On Tue, Jun 15, 2010 at 12:28 AM, Ilya Haykinson <haykinson@xxxxxxxxx>wrote:

> 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.
>

I referenced it because it seemed to offer many of the features that the
group was looking for, and it was/is actively maintained.

With regards to limited adoption, if the group rolled our own, we would have
just as limited adoption, no?  And SUMO seems to be built on
actively-maintained projects.

Regarding the specific processes of support.mozilla.com, what do you see
that is bad about their processes?  The site allows contributors to make
edits in a simple, wiki-like format, and for those edits to be approved by
authorized contributors.  Images and videos can be included in the help.
Content can be translated into multiple languages.  Also, if there are
features that aren't included, could the platform be extended to include
them?


>
> 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.
>
>
Although I like DITA's functionality, I've been looking into it more, and I
think we'd be a good way off from using it.  Not to say that the docs and
manual teams shouldn't pursue it (because I want to), but (for one) the DITA
DTD's and Schemas aren't even packaged in Ubuntu or Debian.  Moreover, the
build toolchain is different and Docbook and Mallard documents, requiring
the DITA Open Toolkit, which is also not packaged in Debian or Ubuntu.

I am interested in packaging these for Ubuntu, though, and have been reading
through the Debian XML policies (
http://debian-xml-sgml.alioth.debian.org/xml-policy/index.html ) as a
precursor to doing so.  If anyone would like to help me with packaging DITA
and the DITA -OT for Ubuntu or Debian, please let me know.

Also, not to overwhelm everyone, but just as a reference for those who may
want to dig into it, here's the DITA architectural and language specs:
architectural spec:
http://docs.oasis-open.org/dita/v1.1/OS/archspec/archspec.html
language spec:
http://docs.oasis-open.org/dita/v1.1/OS/langspec/ditaref-type.html

The architectural spec is certainly easier to digest, but the language spec
is a good reference to have, too.


> 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.
>
>
I am not a programmer, but the manual team seems to have more interest from
people who are programmers.  I'm sure Ubuntu would benefit greatly from a
full-featured, open-source help-authoring tool.

Jim