4.6 documentation

[Mike Massonnet]

2009/2/15 Jasper Huijsmans <jasper at xfce.org>:
> Heya,
>
> (yes, I'm still around. mostly just lurking though :()
>
> 2009/2/14 Nick Schermer <nickschermer at gmail.com>:
>>>> I was assuming the Xfce wiki, of course if you intend to setup a new
>>>> wiki or reconfigure the Xfce wiki that can be avoided.
>>>
>>> Nope, within the xfce wiki it is possible to lock pages to a group of
>>> users.
>>
>> It will be a separate wiki. I've written some dokuwiki plugins to
>> define for example keybindings, menu choises, gui buttons, etc. Stuff
>> we use for writing gui documentation.
>>
>> Personally I think 2 permission groups is good enough: admins and
>> editors. Editors can change all the wiki contents, so 'translators'
>> can fix typos or complete the C manual too. They are already people we
>> allowed. It should also be possible for them to see the generated
>> docbook page (will be a link at the bottom of the page), the script
>> 'forces' strict writing of the contents and it will die if you don't
>> follow the rules, better let them fix it. There will also be a few
>> admins to manage the users accounts.
>>
>> We shouldn't make it too complicated or it will work against us!
>>
>
> I would be really glad if this works out!  I have a bit of a soft spot
> for documentation, since that is what got me started working on Xfce.
>
> Do we still want docbook?  On one hand it is good because it's (kinda)
> standardized and can be rendered in many different formats, but if
> nobody ever does that...
>
> One problem used to be, which might have been fixed in the meantime,
> that docbook does not properly support rtl languages, whereas good ol'
> html does.  At least that is what I was told.
>
> If all we ever do is pack it up and put it in a tarrball along with
> the code, html might be good enough.

I like docbook (I'm biased), it is cleaner than html, and oriented for
documentation.

> Anyway, online collaborative editing could be very beneficial to the
> quality of our documentation and its translations.

I think we can all agree that having a wiki to edit documentation
eases the contributions by not enforcing the knowledge of docbook thus
making it more accessible.

I found out docbookwiki, which looks ideal, have a look at it:
http://doc-book.sourceforge.net/homepage/ there is also a demo:
http://doc-book.sourceforge.net/books/. However i don't recommend it
for production, from a quick look it is not well maintained, there is
already a new project not yet complete (docbookeasy), so I guess it is
worth looking for other projects like this one.

On a off-topic note, I just tested the help in gimp (cause it uses
libwebkit now, yey) but the doc was not installed... so it proposed me
in a yes-no dialog to check the doc online. That's a nice thing.

Cheers
Mike