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/
signature.asc
Description: PGP signature
_______________________________________________ Xfce-i18n mailing list [email protected] http://foo-projects.org/mailman/listinfo/xfce-i18n
