Documentation proposal

[Jérôme Guelfucci]

Nick Schermer:
> 2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
>   
>> On Mon, 4 May 2009 10:49:07 +0200
>> Nick Schermer <nickschermer at gmail.com> wrote:
>>
>>     
>>> 2009/5/4 Jannis Pohlmann <jannis at xfce.org>:
>>>       
>>>> I'm against too complex hooks. I also have the feeling that the good
>>>> old gettext translation method is not really suited for continuous
>>>> text. IMHO the little syntax overhead you have with reST makes .po
>>>> files almost pointless.
>>>>         
>>> The point is tracking changes. The advantage of po files it will
>>> result in fuzzy or untranslated strings, for separate files you have
>>> to compare it with the original version. The syntax overhead is not
>>> the point, keeping in sync is.
>>>       
>> I've just read Mike's mail on xfce-i18n. If translators feel that
>> they are more comfortable with rst2xml + xml2po + xml2rst rather than
>> translating the docs by creating a copy of the original english docs,
>> that's fine with me. I'm not (really) a translator so I'm not in the
>> position to make this decision - translators should decide here.
>>     
>
> >From this point I think we make it too complicated. Why not put all
> the docs in 1 git module, use docbook + xml2po for translations
> (translations also in the docs module) and hooks or submodules to link
> the docs to the core modules.
> We could provide some extra scripts in the docs module to make this
> easier and automate some stuff.
>
> reST simply does not quite suit our needs IMHO, we could use it and
> work around all the problems, but that will result in more
> maintenance. Docbook is a bit rough on the edges, but it works fine
> (proven concept) and there are a lot of (good) tools for translators
> and developers.
>
> Nick
> _______________________________________________
> Xfce4-dev mailing list
> Xfce4-dev at xfce.org
> http://foo-projects.org/mailman/listinfo/xfce4-dev
>
>   
Hello,

I think we should take into account who is going to write the 
documentation: docbook may be 100% fine for developpers but it's really 
unfriendly. During the 4.6 cycle I contributed to the xfdesktop 
documentation and I can tell that docbook is really a pain for newcomers 
and that it could deter some potential contributors.

Moreover I do not think the GUI items thing of docbook are crucial, 
currently we have an almost 100% outdated documentation. I think most 
users won't care if the new documentation does not look as polished as 
before, they want something that can help them. If rest can help 
improving the contents, it's definately a positive point that should be 
taken into account.

Just my 2 cents,

Jérôme