Documentation wiki on docs.xfce.org

[Nick Schermer]

Folks,

This was bought up on #xfce-dev yesterday and I'd like to discuss this
on the ml.

It is about the endless problem of documentation. I know this does not
apply to all packages, but most of them have no or outdated docs. Main
reason is that docs are hard to write (docbook, mallard, it makes not
much of a difference), repository access.. you name it, but fact is
that (does not apply to you Shara), not much people work on the
manuals.

Main argument for offline docs is for people without internet. I agree
with that, but as a start it is better to have good online docs than a
"page not found" warning in your web browser, because that is what
most Help-buttons will show you.

So this is what I suggest:

1. Remove api docs from docs.xfce.org (those are in the packages).
2. Setup a wiki on docs.xfce.org with limited access on the English
versions (translators only need to register, we can optionally work
with team coordinators here, but I don't this that is required).
3. Enable the translation plugin like we have on wiki.xfce.org.
4. A script on the server we can use for redirection (function belows
goes here) (checks for translation, else redirect to English version).
5. A function in libxfce4ui to ask the user to go online and visit the
docs (xfce4-panel already has something like this).
6. Some guidelines doc writers have to follow.
7. Start with online docs, yeey! Begin with the packages that do not
have packed docs.
8. Benefit! and get more documentation contributors.

In the feature we can look to get regular pulls from the wiki into the
xfce4-docs page so we can still ship offline versions. Not impossible
to automate this on the server (daily tarball generation or something
like that) and can also adjust the function in point 5 easily to
handle this.

Another discussion point will be versions of the docs (for 4.8, 4.10
etc). I don't think this is much of a problem for now, but we can
always branch on the wiki, so we get the following layout (following
git and archive):

/xfce/getting-started
/xfce/xfce4-panel
/xfce/xfce4-panel/clock
/xfce/xfce4-panel/preferences
/xfce/xfce4-settings
/xfce/xfce4-settings/appearance
/apps/ristretto
/panel-plugins/
/<lang>/xfce/xfce4-panel
/<lang>/....

Then in the future we can copy the "master" docs to
/xfce/4.10/xfce4-panel if needed.

I can take care of the first 7 points and get everything started. Then
we obviously need people to work on the docs, but I think everybody
agrees with me this is not much of a problem in a wiki.

Nick

PS. if you vote against this as a user, the only way you can do so is
by submitting docs! And it is safe to say your not going to do that...