[Xfce-i18n] Notes from what has been said Re: Documentation proposal

[Mike Massonnet]

Ok people, I scribbled some notes from what has been said.

As pointed out several times, documentation in Xfce sucks. Developers
suck too, they usually do everything on their own, but when it comes
to documentation there are some pieces copied from here and there.
There ain't any templates, so it is mostly an adapted copy.

Those are reasons enough that it must be made better. (Go-go Jannis :-P)

What has to be figured out:

    * Centralized documentation repository.
    * Documentation syntax.
    * Translations.


==== Centralized Repository ====

What we have (documentation per components):

    * Each project has its own documentation.

What we want:

    * ?

Pros:

    * With a centralized repository we have documentation maintainers.
    * We don't need to shake the hell out of a developer to update his project.
    * Translators can point to one place if they wish to localize the
documentation.
    * Possibility to build an up-to-date index.

Cons:

    * Projects are not distributed with documentation. (It should be
possible to set up git-submodules)
    * It is not possible to use the magic of the tool chain, for
example autotools allows to build .ext.in files to .ext files and
replace @VARIABLE@ against the project name, the version, the author,
etc.


==== reStructuredText Syntax ====

What we have (DocBook):

    * DocBook is known to be well suited for documentation but also
has a overhead for a lot of stuff.
    * There isn't any template, but a template is already very big
without containing a single line of documentation.
    * The tags are numerous and usually needs you to have a bunch of
docbook.org tabs open.

What we want:

    * Files that are easy to write, easy to maintain, for example
reStructuredText files.

Pros:

    * reStructuredText files are far more easier to maintain.
    * They are easy to write and easy to read.

Cons:

    * Only a restricted set of formatting.


==== Translations ====

What we have (po files):

    * The po-doc directories have one benefit that the translations
are always synced with the english text.
    * It notifies the translator of changes.
    * The translation is awkward, it isn't fun at all and doesn't feel natural.

What we want:

    * Copy the orignal documentation files and translate them.

Pros:

    * It is easier to translate the documentation to its locale.

Cons:

    * No good way to keep translations up-to-date.
    * cf. Jari's post, e.g. using the CVS to track changes and made up
a statistics web page.

And that's it!

Mike