[Xfce-i18n] Documentation wiki on docs.xfce.org

[Mike Massonnet]

2011/12/30 Nick Schermer <nickschermer at gmail.com>:
> 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.

2011 showed documentation didn't take off, and yes writing doc in
mallard is nice but it's not wysiwyg and thus needs good practice.
When you get to the point of writing the documentation, you put a lot
of labour in it and yet afterwards it needs a lot of time for being
kept up to date.

One fact we sticked to Mallard was the ability to use PO files for
translation, which has the benefit of marking single paragraphs as
fuzzy or new when the whole documentation is updated. With a wiki the
translator has to f.e. lookup the history to know what changed, a
recommandation can be to follow the recent changes from the wiki.

> 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.

yeey! for wysiwyg edition with quick "edit" buttons beneath each
section, and type documentation not code.

> 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.

Dokuwiki provides HTML exports, for example:
http://wiki.xfce.org/tips?do=export_xhtml / export_raw
http://wiki.xfce.org/_export/xhtml/tips (alternative url)

...but you still miss the images offline.

> 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 would rather see the master version (and older versions) in a
subpath, and keep the stable version visible by default:
/<lang>/<class>/<project-name>[/master|/4.6|/4.4|...]

We can also include a plugin (write our own) that checks for other
versions in the subpaths and display them on the page.

@Jannis, the translation plugin puts the root namespace as the default
language (in our case english) and subpaths for each language. It's
not possible with this plugin to have a /C subpath, this would mean
the translated pages would look like /<lang>/C/<page>/...

> 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...

Mike

PS: nice one :-)