Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 27 Aug 2011 13:56:16 -0500
From:      Evan Busch <>
To:        "" <>
Subject:   Re: A quality operating system
Message-ID:  <>
In-Reply-To: <>
References:  <> <> <> <>

Next in thread | Previous in thread | Raw E-Mail | Index | Archive | Help
I can see this will be important here:

On Wed, Aug 24, 2011 at 9:32 PM, Polytropon <> wrote:
> 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".

The problem with your statement is that it does not allow for general
critique, which is also needed. If something shows up in more than one
place, it is a general critique.

> 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.

See the Wikipedia page above -- the problem isn't one of user
competence, but of poorly-written documentation that is fundamentally

Have you looked at any of the documentation coming out of Redmond right now?

How do you think FreeBSD's documentation stands up to that?

> 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.

The question isn't form, but content.

> 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.

I think I'm talking about professional level documentation, not a
specific "style."

> 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.

We're talking end-user documentation here.

> Here the "one size fits all" problem arises. It's really hard
> to make documentation "for everybody".

I disagree. It's very clear what must be done because multiple archetypes exist.

> 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.

If so, it's just them trying to cover up the inherently defensive and
reactionary nature of their comments.

Would they send such an email on a business list?

> You can "predict" that everywhere. Just go to any halfway
> specialized setting and make claims about something not
> meeting your requirements

I've never had this problem when the claims have been stated
professionally -- only here.

Want to link to this message? Use this URL: <>