Documentation proposal

[Jannis Pohlmann]

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.

Ok, let's get to the point. I'm proposing that we create a new
component to include the user guide and other user documentation (like
application manuals, glossary, tips & tricks, ...). The name? I'd
suggest something like xfce4-docs or xfce4-documentation. xfhelp4 is
part of xfce-utils so I suggest we make xfce-utils depend on this new
package. That way we make sure it's always installed together with Xfce.

Jim pointed me to reStructuredText [1] yesterday. I tried it today.
It's very easy to use, the reST sources are very easy to read and the
best thing is: there's a tool called Sphinx [2] which generates HTML and
PDF from it and links different reST source files together.

So my suggestion is that we create xfce4-docs (or whatever name we
decide on) and write the documentation using Sphinx/reST. For
translations we can create copies of the original documentation
inside the same package, just like we do right now.

For releases we could simply build the docs and upload the HTML to our
website. We could also consider running a cronjob for generating and
uploading in-development docs once a day or so.

An example of how the HTML docs generated by Sphinx look like
can be seen on [3]. The generated HTML even provides a searching
feature based on a searchindex.js. The HTML templates and CSS can be
modified easily.

Sphinx would be a build-time dependency and most binary distributions
would only package the generated HTML/PDF docs anyway. Nothing to worry
about IMHO.

I'm volunteering to set up the repository, but first I need some input
from Jim, our core developers and the interested translators. Thoughts?

Cheers,
Jannis

[1] http://sphinx.pocoo.org/rest.html
[2] http://sphinx.pocoo.org/
[3] http://docs.python.org/dev/
-------------- 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/20090503/b4a459d0/attachment.pgp>