Documentation proposal

[Jannis Pohlmann]

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.

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

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20090505/9077ef4e/attachment.pgp>