[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: (Off Topic ) Open Source: The Model Is Broken ??



On Sat, Dec 06, 2008 09:31:55 AM -0800, Les wrote:
> On Sat, 2008-12-06 at 12:04 +0100, M. Fioretti wrote:
>
> > 1) be ABLE to write good documentation. You yourself acknowledged
> >    good "documenters" are scarce. You're either good at it or you
> >    aren't, it's just like programming or any other complex
> >    creative activity.
> ....
>
> I haven't written anything for LINUX, but I can tell you that the
> biggest issue is getting "something" on paper (in bits?).  Once the
> first effort is in, LOTS of people can "fix it" and even copy it and
> redo some or most of it... That's OK, if your intention is to get
> information into the Linux sphere.

I was **explicitly** speaking, see the quote above, of **good**
documentation. And since I already wrote how weak I find assumptions
like yours above, I'll simply point you to Point 1 of
http://digifreedom.net/node/61.

> So, my advice is "just do it".  someone will fix it.

Here I could simply answer "after you, please" or repeat what I wrote
above: we're talking about quality, not quantity. But I have a very
fresh, real world example of somebody who "just did it" and things
didn't go as you say, so I'll let that speak for itself. Have a look
to the thread about Postfix How-tos starting at
http://archives.neohapsis.com/archives/postfix/2008-12/0133.html

the thread summary is:

- postfix gurus only wrote good, but too difficult docs
- some popular postfix howtos (by other people who "just did them")
  are broken
- newbies read **those** docs only, as the "official" ones are too
  difficult
- they make mistakes following those docs, ask how to fix them to the
  postfix list. This happens several times a year.
- every time, postfix gurus answer "those docs are broken, check the
  official docs"
- for any number of reasons, postfix gurus have no plan to write better
  howtos themselves
- nobody but postfix gurus could write better howtos than those
  already available, or fix those ones. Excepted a good technical
  writer **paid** enough to spend on the subject lots of time, since
  it isn't an easy task by any means.

Marco
-- 
Your own civil rights and the quality of your life heavily depend on how
software is used *around* you:            http://digifreedom.net/node/84


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]