| 1 |
On Sun, Aug 08, 2004 at 04:00:34PM -0400, Alexander Plank wrote: |
| 2 |
> Maybe a good idea would be a type of system in which edits would need |
| 3 |
> to be certified as accurate by a developer before added to the site. Or |
| 4 |
> maybe we could have a system where the "unstable version" is editable |
| 5 |
> by anyone, but the stable version (the one that people read if they |
| 6 |
> want to follow a guide) needs to be fact checked by a developer. |
| 7 |
|
| 8 |
The main issue with user-contributed documentation isn't to convert it to |
| 9 |
GuideXML (really, I can do that in a few minutes for each page), but rather |
| 10 |
to maintain it. Although some contributors keep on updating their |
| 11 |
documentation we've put online, most user-contributed documentation is |
| 12 |
updated by Gentoo (Documentation) Developers who know the subject well |
| 13 |
enough. |
| 14 |
|
| 15 |
Maintaining a guide is horrible if you don't know the subject. Take ALSA for |
| 16 |
instance: the main author of the guide doesn't even use Linux anymore. It's |
| 17 |
widely used but we have some bugs pertaining to MIDI support: who's up for |
| 18 |
the challenge? I don't use MIDI and I don't think any of the doc-devs do. So |
| 19 |
how would we update the guide? |
| 20 |
|
| 21 |
If we would just trust the user's accuracy we might end up with what we now |
| 22 |
have on the "Documentation, Tips & Tricks" forum on |
| 23 |
http://forums.gentoo.org: lengthy discussions about how wrong this is and |
| 24 |
what needs to be added and rewritten and ... |
| 25 |
|
| 26 |
Allthough that approach leads to documentation that is fairly accurate, it's |
| 27 |
quite difficult to write it fluently for the user. Try writing a guide on |
| 28 |
Software Watermarking if you don't even know how an application behaves |
| 29 |
in-memory. |
| 30 |
|
| 31 |
I can only *hope* that users keep on contributing documentation to the |
| 32 |
Gentoo Documentation Repository; if I or any other doc-dev knows the subject |
| 33 |
it will easily be added. |
| 34 |
|
| 35 |
Wkr, |
| 36 |
Sven Vermeulen |
| 37 |
|
| 38 |
-- |
| 39 |
Bent Hindrup Andersen, Danish MEP, about the Software Patent Directive: |
| 40 |
The approach of the Commission and Council in this directive is shocking. |
| 41 |
They are making full use of all the possibilities of evading democracy that |
| 42 |
the current Community Law provides. <http://lwn.net/Articles/84009/> |
Archives