Documentation proposal

[Jim Campbell]

On Mon, May 4, 2009 at 5:48 PM, Jannis Pohlmann <jannis at xfce.org> wrote:

> On Mon, 4 May 2009 12:54:00 -0500
> Jim Campbell <jwcampbell at ubuntu.com> wrote:
>
> > Hi All
> >
> > On Sun, May 3, 2009 at 2:31 PM, Jannis Pohlmann <jannis at xfce.org>
> > wrote:
> >
> > > Hey,
> > >
> > > Jim and I are currently investigating ways to improve the user
> > > documentation in future releases of Xfce. I think we all agree that
> > > the current situation is far from optimal and we really *need*
> > > improvements here. I think we also agree that user documentation is
> > > something our core developers don't want to maintain themselves
> > > (IMHO we're busy enough already).
> > >
> > > Last year I promised to do something about this by forming a
> > > dedicated documentation team. Today, I'd like to make a proposal to
> > > get this "operation" started. Warning: this mail contains a lot of
> > > text.
> > >
> > > We've briefly discussed the option of a wiki-based solution but I'm
> > > a bit worried that exporting could become a mess. Thus, the
> > > approach I'm suggesting here is based on a normal repository, and
> > > not a wiki.
> > >
> > > Furthermore, I have the feeling that per-component docs, which is
> > > what we have right now, are confusing and too complicated for the
> > > people motivated to improve our documentation. This is why my
> > > proposal is about creating a separate documentation package.
> > >
> > > And just like our website, the docs are a pain to translate because
> > > they're written in Docbook or even HTML (correct me if I'm wrong ...
> > > I've lost the overview myself). That's why my suggestion involves a
> > > powerful markup language with less syntax overhead than Docbook or
> > > HTML.
> > >
> > >
> > I will need to be brief in my response here, but wanted to pipe in
> > with something.  First, thanks to Jannis for sending out this initial
> > note, and I'm glad to see some interest in this.
> >
> > I don't have a lot of experience with reStructuredText, but combining
> > it with Sphynx does seem like a relatively easy way to get
> > documentation together in a manner that avoids the complexities of
> > docbook.  However, I was glad to see others bring up the issues of
> > there not being any GUI-specific markup in reStructuredText, and the
> > translation-related issues.  Those were two of my concerns in my
> > initial examination of the syntax.
>
> Again, GUI-specific markup could be added as an extension to Sphinx. It
> involves a bit of Python programming and I could help with that.


I found something that could work pretty well for that:
http://sphinx.pocoo.org/markup/inline.html (see the section at the bottom of
the page, "Other semantic markup.")


> > We will need to see if there is a way around the lack of gui-specific
> > markup, and will have to see how clean the output is between current
> > docbook sources, reStructuredText, and xml which could be translated.
> > My initial thought is that we *would* need xml sources to assist with
> > translations.  If the initial conversion from docbook to
> > reStructuredText is a little messy, but (after cleaning it up) it
> > converts well between formats - that would be ok with me. If it's
> > not, though, we may have to reconsider this approach.
> >
> > Also, the GNOME documentation team is currently going forward with
> > Project Mallard, an xml-based documentation markup that is much
> > simpler than docbook, and promises to be easier for contributors to
> > use. I don't have a lot of specific info on it now because it's in
> > beginning stages, but there's a Writing Open Source conference that
> > I'm going to in June, and the head GNOME-doc guy is pushing to get
> > things ready so he can debut the language at that conference. His
> > plan is to have it so that old docs could remain in docbook while new
> > docs could be written alongside them in Mallard.
> >
> > http://live.gnome.org/ProjectMallard
>
> I'm sceptical about this. I think Docbook is not only hated because of
> its complexity but also because of the markup overhead. It just makes
> you type more and the sources are more difficult to read and also a bit
> more of a pain to maintain in a version control system than
> (almost-)plain text files.
>

Ubuntu maintains docbook-based docs in bzr, and it seems to work well
enough. And I personally don't have much of a problem with docbook's markup,
and (from what I can tell) having things in xml format assists with the
translation process.

Others have commented on some of xml's advantages with regard to
translations... For example, if one string changes in xml-based docs as part
of a bug-fix, the translations can be updated so that only that one string
would need to be re-translated. I don't think that would be possible with
straight-up reStructuredText / Sphinx, would it?  There is also the issue of
multiple ocurrences of text ... with xml-based docs, you can translate just
the one string, and it will be translated everywhere that string is used.

If we can find a way to get documentation out in a non-xml-based manner
along with translation workflows that will work for translators, though,
then I'm ok with that it. Per my points above, I just want to make sure we
cover our bases.  Our needs may not be the same as GNOME's . . . Xfce is
obviously a smaller project, but I think that internationalization is pretty
important given that Xfce is supposed to run on older hardware. Even if we
*need* English docs now . . . I wouldn't want a solution that makes
translations prohibitive.

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20090504/36770b22/attachment.html>