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

[Brian J. Tarricone]

Jasper Huijsmans wrote:
> 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.

Sure: find these people and kick off the project.  They all need to
either be native English speakers, or you at least need to find a good
core of native English speakers to proofread everyone else's work.

Stephan, I hate to pick on you specifically (especially since you're
trying to help!), but just to illustrate how difficult it is to find
people with the proper English skills...  Your use of a hyphen in
"Xfce-Userguide" and lack of a space between "user" and "guide" is the
type of thing I'm talking about here.  I guess I see it most often with
German speakers, or speakers of languages influenced by German (not that
English isn't one of them): odd hyphenation, odd word concatenation, odd
capitalisation... stuff like that.

I can usually divide non-native English speakers into two groups: 1)
those who don't speak it very well, and sometimes are hard to
understand; and 2) those who speak it very well, and are very easy to
understand, but who occasionally bring attributes of their native
language into their English.  It's not "bad", per se; it's just very
jarring to see non-English-isms in written English text.  I speak to
people all over Europe and Asia as a part of my job, not to mention
interacting with a bunch of people of various backgrounds and locations
online, and it's very rare for me to come across a non-native speaker
who doesn't display these sorts of... oddness.

Then again, you can't always get a good impression of a person's
'formal' writing skills by hearing them talk, or by reading more
conversational emails.  But you at least get a taste.

(All this is, of course, completely ignoring another group: actual
native English speakers who write poorly in their own language.  Sadly,
I know plenty of Americans who fit this description.)

Ok, I'm starting to get off on a tangent.

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

Agreed, that's definitely useful.

>> Don't get me wrong, current docs are pretty good but
>> they are always out-of-date,

Everyone seems to say this, but I've never seen the docs out of date for
an actual stable release of Xfce.  (No, the 4.4 betas and RCs don't count.)

>> and do not always answer the questions
>> that users have (the curse that rests on docs it seems)

*nods* ...

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

Sadly, I've found that most users don't read documentation either, but
that's another issue.

>> Because bad docs are worse then no docs they need to have some sort of
>> supervision.

Definitely, and this is one of the reasons I disagreed so heavily with
making the docs a wiki-based project.

>> 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'm thinking something like that, but maybe have a (single?) doc
maintainer per module (not saying that a single person can't be
maintainer for multiple modules), especially at first) who nominally
writes and proofreads the docs, but who also is in charge of
proofreading, editing, and integrating patches/changes submitted by
other people.  Maybe this person could also commit localised changes to
the po-doc dirs, though that could still be handled in the same way on
xfce-i18n as normal po files are committed.

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

That's my fear as well.  But don't let that stop anyone - if people want
to come forward and commit to do this, that would be great.  Maybe as a
start, someone should create an xfce-docs mailing list and invite people
to join?  After a few days, start a discussion with some important goals
and objectives, and see about getting people to start working toward
them?  Just ideas...

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

Hear, hear...

	-brian