Documentation on wiki?

[Stephan Arts]

On 12/4/06, Brian J. Tarricone <bjt23 at cornell.edu> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> samuel verstraete wrote:
> > Then why not create an extra tarball with the documentation?
>
> How is this any different from what we do now?  Either we have the docs
> on the web, and make a tarball of it to distribute like you suggest; or
> we distribute the docs with the source packages and put a copy on the
> web, like we usually do.
>
> > I, for one, but i'm sure there are tons of
> > others, never check documentation installed on the computer.
>
> That makes zero sense.  And besides, it's a single anecdotal data point
> and therefore useless.  True statement from my perspective: I, for one,
> but I'm sure there are tons of others, always check on my computer first
> for documentation when I need it.
>
> > Guaranteed it's outdated, wrong
>
> If we distribute it with version X of the software, and you have version
> X installed on your computer, then by definition it's not outdated or
> wrong.  If there are errors, that's what bug-fix releases are for.  We
> always spend the last frantic moments before a stable release checking
> our documentation.  Is it perfect?  No, of course not, but the quality
> is generally high.  We also take the time to proofread each other's work.
>
> > and/or difficult to find/read.
>
> Clicking on the 'Help' button in the appropriate settings panel is hard
> to find?  Really, if you can't find that, putting it on the web isn't
> going to help you.
>
> I also don't see how letting a bunch of random people edit it will make
> it easier to read.  Looking at the first cut of the wiki, I see many
> spelling and grammatical errors.  And I'm not surprised; from my
> experience, most of the people that post to the Xfce lists and forums
> and participate in our community are not native English speakers.  I'm
> not trying to be mean or insulting; that's just how it is.  (When I can
> speak everyone else's native language as fluently as I speak English,
> *then* I'll feel free to criticise.)  This kind of thing works for
> Wikipedia because of the huge number of native-speaker eyeballs watching
> pages, but we just don't have the same community.
>
> > Releasing a tarball would be easy and everybody could install the
> > documentation if he/she wants to install it. And if he does install
> > it, he's prolly very aware of it and knows how and where to find it.
>
> Again, not an issue.  It's easy to find, and if you install our
> packages, it's *always* installed.  Not to mention that, as it stands
> now, only the docs for what you actually install get installed.  If we
> make one big tarball, we'll also be installing docs for modules the user
> may or may not have installed.  That could cause some confusion.
>
> There's also the issue of translators.  We haven't had much in the way
> of translated documentation in the past because a) the translators just
> don't know about it, b) the docbook XML is a bit of a pain to translate.
>  However, now we can do this translation via .po files just like the
> software itself.  Having the moving target of the wiki will guarantee
> that the English version and any translated versions will almost always
> be out of sync.
>
> 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.

Stephan