A quality operating system

[Polytropon]

On Wed, 24 Aug 2011 21:02:18 -0500, Evan Busch wrote:
> I didn't expect this much response.

You always get what you deserve on this list. :-)

No, seriously: There are participants of this list who
understand complains and other statements in a critical
tone as inspiration for improvement. But allow me to say
that _if_ you are interested in contributing in _that_
way, you should always bring examples and name _concrete_
points you're criticizing, instead of just mentioning
wide ranges of "this doesn't conform to my interpretation
of what 'professional' should look like".

As long as you are professional and fair, you will get
a polite and substantial (!) response.



> Every professional documentarian I've encountered agrees with you.
> It's inconsistent, wordy, and has no concept of the order of
> introduction of its concepts. No professional software package would
> ship with documentation this bad.

Depends.

Have a look at IBM's mainframe or midrange documentation.
For those who are working with this very special kind of
documentation, it may appear fully understandable, helpful
and direct. For hobbyists or newbies, it may look to be
the complete opposite: Not understandable, no structure,
way too verbose, and not helpful at all.

You can also see how Sun publishes documentation for their
Solaris OS. Did publish. Past tense. :-)

In most cases, documentation requires you to have a minimal
clue of what you're doing. There's terminology you simply
have to know, and concepts to understand in order to use
the documentation.

Different kinds of users have different preferences. Some
like to use the web, like to use Wikis and discussion boards.
Others like to use structured web pages. Again, other like
web pages too, but want to have as much information in _one_
(long) page. And there are those who do not want to depend
on the web - those like man pages.

If you're used to some specific _way_ of documentation, you
will maybe value anything that's _different_ from that way
as being inferior, non-professional, or less helpful.

Also keep in mind that especially for developers, the SOURCE
CODE also is an important piece of documentation. Here FreeBSD
is very good, compared to other systems.



> The multiple grammatical errors only
> enhance the sense of its fundamentally confused nature as a document.

Oh, then don't visit the non-english translations of the
documentation. :-)




> On Sat, Aug 20, 2011 at 2:08 PM, Polytropon <freebsd at edvax.de> wrote:
> >
> > Well, in _this_ area, I would also agree that work should be
> > done to concentrate documentation, e. g. make an "essence" from
> > knowledge and examples in mailing lists, web forums and so on.
> > But there are too many of them, and you simply cannot put all
> > the possible things into "the one documentation" project.
> 
> This isn't as big of a project as you make it seem. In fact, it will
> reduce your workload and that of your users.

I have worked on documentation projects (in the medical and
technical sector) before, and it was relatively easy because
you KNEW enough, e. g. who your clients are, how they read,
what they need to know, and what they already do know, so
you had a good basis for creating documentation that fits
there needs.

Here the "one size fits all" problem arises. It's really hard
to make documentation "for everybody". What should be in there?
How much detail is needed? What can the reader conclude himself?
Which terminology is he already familiar with?



> I think the comments above provide a good starting point for
> actual discussion.

It would help if you could just bring some examples for what
is lacking in your opinion.



> As far as people proving my point about the BSD community being reactionary:
> [...]
> These angry non-sequiturs just reek of defensiveness.

Note the presence of ":-)" and the abilities of english native
speakers who are much more able to express "between the lines"
than I am, for example.



> I think I predicted these behaviors when I spoke of "cliques" and the
> nasty, elitist side of geek culture.

You can "predict" that everywhere. Just go to any halfway
specialized setting and make claims about something not
meeting your requirements, telling the people they are
not professional and lack the most fundamental things.
Of course there will be some who thing you're just trolling
them, because to _them_, that's exactly what you do, even
if you have other intentions. Interpretation heavily depends
on specific discussion cultures. The way you communicate on
this list, for example, is very different from how you
write Twitter messages, SMS, or act in a different "online
community" (e. g. like WoW gamers with their terminology
and "cultural techniques").




-- 
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...