xfce-docs (Was: Re: Documentation on wiki?)

[Jasper Huijsmans]

Stephan Arts wrote:
> On 12/4/06, Brian J. Tarricone <bjt23 at cornell.edu> wrote:
>   
...
>> I'm not saying we can't improve. We should:
>> 1.  Go over our docs very soon, since we're releasing 4.4.0 soon, and
>> make updates.
>> 2.  Review and proofread our updates, hopefully by asking several
>> native-English speakers to look at them.
>> 3.  Add the appropriate Makefile magic to allow all the rest of the docs
>> to use po-doc directories for translations.
>> 4.  Advertise on the xfce-i18n list that the documentation for module X
>> is ready to be translated, and make sure the po-doc directories get
>> checked out with whatever tools/scripts the i18n guys are using for the
>> rest of Xfce.
>> 5.  After docs are frozen and we make the 4.4.0 release, post the
>> documentation to the website as we usually do.  If new translations
>> arrive after the release, they can be posted to the website early, and
>> then released with 4.4.1.  Ditto for any errors caught after the 4.4.0
>> release.
>>
>>     
>
> Why not set up a separate project, simmilar to xfce-i18n, xfce-docs?
>
> The 'official'-docs-maintainers can then tune the docs of xfce
> projects so they can be distributed as separate docs and fit in the
> Xfce-Userguide as a Chapter.
>
> Most importantly, docs can be written parallel to the project in
> question (from a user point-of-view), instead of the way it is now,
> docs being written by devs (because nobody else does it) from a
> developer stance. Don't get me wrong, current docs are pretty good but
> they are always out-of-date, and do not always answer the questions
> that users have (the curse that rests on docs it seems) by allowing
> other people to contribute to the docs we can get the dust off them.
> And tune them to the end-user better.
>
> (Face it, the docs do not exist for developers)
>
> Because bad docs are worse then no docs they need to have some sort of
> supervision.
>
> That's why i would like to propose the xfce-docs project, a project
> which takes care of all the docs.
>
>   

You mean we'd have doc writers committing to <module>/docs like we have 
translators committing to <module>/po?

I would not necessarily oppose this idea. For this to work there would 
need to be enough interested people with good English writing skills and 
enough time to spend on it. I'm not entirely sure we will be able to 
find those.

Anyway, I would be the last person to claim it wouldn't be nice if we 
had a few more people working on documentation.

    Jasper