Documentation on wiki?

[Brian J. Tarricone]

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

	-brian

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (GNU/Linux)

iD8DBQFFc3H76XyW6VEeAnsRAkS7AKDs6h9rXFXFyp65YALlGqsIAHSNFACdHNGt
1mnYFiiKKsFL2QG3Vb5kWV4=
=iQ+4
-----END PGP SIGNATURE-----