Documentation proposal

[Jim Campbell]

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.

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

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