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

[Les Mikesell]

M. Fioretti wrote:
> 
>>> Right. Now, who could write such good templates, ie distill without
>>> errors those thousands of options and explain the result clearly, in
>>> order to minimize misunderstandings, except the developers themselves
>>> or (much better) some pretty good technical writer who's either paid
>>> to do it or already financially secure?
>> None of the above.  Only a person who actually runs the program in  
>> production over a period of time will have a usable template
> 
> This is exactly what a responsible, professional tech writer does
> before writing. Either he runs the sw himself or nags to death the
> developers and testers to figure out what their notes and internal
> docs mean.

Tech writers and developers often can't test in production scales 
themselves - and developers are way to optimistic about things.  I'd 
expect someone who actually keeps a large university mail system running 
to have a much more realistic config file than someone who only looks at 
the theory.

>> The problem is that he [who has a usable template] has no way to
>> share his work with the thousands of other people who could use
>> exactly the same setup
> 
> This is false. All that person should do is publish online one page
> with that template and a few clearly written explanations of its
> content. 

That's equally true for source code, but we don't expect users to build 
their systems from scratch by gathering up source code page by page from 
random users they don't know in random, distributed places, do we?

> It's writing the clear explanation which is hard, which is a
> good part of why those templates don't pop up every day.

Explanations are mostly irrelevant if you it works like an appliance. If 
you need details you can go to the source.

>> Who could fix it?  What we need is a location and mechanism for
>> admins to share their config files with similar tools that code
>> developers have to maintain versions/branches etc., and view diffs
>> across them.
> 
> Les, I have made one general comment about how difficult it is to
> write good documentation on whatever subject, never mind Fedora. Now
> you are talking of something which has nothing to do with the topic I
> suggested. The fact that I used a Postfix example doesn't mean that
> the "good docs" problem is only for initial configuration, I thought
> that was clear, sorry.

Postfix is a perfect example. Very few people should ever need to know 
any config options for mail systems.  They just need one installed that 
works in one of some small number of siturations.

> Having a config files repository would be absolutely useless for a
> newbie user of, say OpenOffice or Kde.

Agreed - there is a big difference in end user run-time operation and 
administrivia.  But they aren't treated differently in the 
distributions, which contributes to the reputation of open source 
documentation that started this topic.

-- 
   Les Mikesell
    lesmikesell at gmail.com