Documentation wiki on docs.xfce.org

[Jannis Pohlmann]

On Fri, 30 Dec 2011 22:14:49 +0100
Nick Schermer <nickschermer at gmail.com> wrote:

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

I don't think docs are hard to write per se even though good, consistent
docs that are written with a proper concept in mind take effort. But
yeah, there clearly is an entry barrier for people who could
potentially contribute useful documentation for users, partly due to
needing a git account and partly due to Mallard and Docbook not being
as easy to write as wiki pages or blog entries.

So, yes, it would be nice to solve this problem once (and for all?).

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

Some people may disagree with the following statement but many people
have written useful instructions related to Xfce all over the web, so
maybe those are worth more than a half-executed "proper docs" attempt.

What I'm trying to say is that maybe a publicly writable wiki would be
ok as well, with guidelines and a few people watching over the whole
thing. Yes, wiki is not the ideal format for docs (e.g. less
custom-tailored and user-friendly-searchable than a Mallard database)
but---I agree with Nick here---it's probably much better than (almost)
nothing at all.

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

Sounds alright to me.

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

An idea that I just proposed on IRC is to have a global xfconf key that
specifies the base URL for documentation lookup. So if there was a
function in libxfce4ui to open a docs topic, it could use this key and
distributions could decide on their own whether to create an offline
docs package and change the key to use that or not.

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

I'm not sure we need the /xfce, /apps separation in this case. Do we
ever have name clashes? And maybe it should
be /C/<appname>, /fr/<appname> etc. rather than having one toplevel dir
for English and subdirectories for the different locales, which feels a
bit "asymmetric".

I'd say: go for it. There's nothing to lose really, as you correctly
pointed out.

  - Jannis