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

[Stephan Arts]

On 12/20/06, Brian J. Tarricone <bjt23 at cornell.edu> wrote:
> 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 don't mind, i totally agree, (btw, capitalization is with a 'z' ;)
just kiddin').

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

True, but the wiki could be a good battlefield for unofficial docs,
and every now and then it can be a sort of feeding ground for the
'official' docs.

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

Perhaps we should set up some review-board for the docs?

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

Stephan