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@xxxxxxxxx
--
fedora-list mailing list
fedora-list@xxxxxxxxxx
To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-list
Guidelines: http://fedoraproject.org/wiki/Communicate/MailingListGuidelines
