Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 28 Aug 2011 05:09:26 +0200
From:      Polytropon <freebsd@edvax.de>
To:        Evan Busch <antiequality@gmail.com>
Cc:        "freebsd-questions@freebsd.org" <freebsd-questions@freebsd.org>
Subject:   Re: A quality operating system
Message-ID:  <20110828050926.4e7d0389.freebsd@edvax.de>
In-Reply-To: <CAC1X_0bXSXMW_AEPZMM_N5Lxi2F3J5hjR7m1gbyhBK1_W4eeWw@mail.gmail.com>
References:  <CAC1X_0bP8SeyqMaR68AQPMzT%2Br-isv4h0bJPdtaF3377bQ%2BajQ@mail.gmail.com> <16851_1313817220_4E4F4284_16851_6517_1_D9B37353831173459FDAA836D3B43499C521886E@WADPMBXV0.waddell.com> <CAC1X_0bs-Bg1VDiaTnXUifGfPKbtAibH%2BzfxV8=RPCMHJKNLVw@mail.gmail.com> <20110825043208.fe201707.freebsd@edvax.de> <CAC1X_0bXSXMW_AEPZMM_N5Lxi2F3J5hjR7m1gbyhBK1_W4eeWw@mail.gmail.com>

next in thread | previous in thread | raw e-mail | index | archive | help
On Sat, 27 Aug 2011 13:56:16 -0500, Evan Busch wrote:
> I can see this will be important here:
> 
> http://en.wikipedia.org/wiki/False_dilemma
> 
> On Wed, Aug 24, 2011 at 9:32 PM, Polytropon <freebsd@edvax.de> 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.

No. General critique would require to be general, means:
it would have to apply in all (or at least most) places.
To advance from specific to general critique, it would
be useful to show at least _some_ examples where it
would apply, and then say something like: "There's more
around the corner."

But _before_ considering general statements, specific
ones would have to be discussed, just to make sure the
one that came to your mind wasn't an exception of the
rule.

>From logic, you should know that allquantified statements
(those including "all", "none", "every", as well as "none"
or "never") are easy to disprove: Only one (!) counter-
example is required.

A = q ^ w ^ e ^ r ^ t ^ z ^ u ^ i -> false <===> (at
least) one of (q, w, e, r, t, z, u, i) is false, to
put it into a formal expression.



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

Oh again you put additional emphasize on it: "fundamentally".
This implies there's a general problem with the documentation.
Could you please _name_ that problem, instead of just mentioning
that there is one?



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

Oh god no! Why wouold I look into disorganized documentation
that cannot even be received by blind users, and that invents
arbitrary words for established technical terminology, changing
all the time? :-)



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

Wery well I'd say: It can be accessed offline, for free, and
by all audiences (including exceptional ones such as blind
or deaf users).



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

Form and content have to be matching when you're talking
quality. Would you accept a letter from your local tax
administration that is correct by content, but written
on used toilet paper? On the other hand, how would you
think about a book that is pure crap, but written on
golden paper with leather?



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

Professional always implies a specific target audience which
has the abilities to learn how to use a given kind of documentation.
As I said, mainframe documentation is _very_ different from
what you might know, but it is _extremely_ professional for
those who deal with it - to solve problems.



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

Suddenly? I just thought we would talk professional documentation
here...

By the way, a thing like end-user documentation does not exist.
End users do not need documentation. They don't read anything.
At _most_, they'd look at colored pictures, but not act according
to them. Documentation is the first thing they throw away
(in many cases right before they throw away installation
media), because "they don't need what they don't know".

Do I have a strange look at end users? Maybe, but according to
my observations and experiences, it's a realistic look. Yours
might be quite different.



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

Then, how would you suggest a "one size fits all" documentation
should look like? Maybe you can point to a resource available
on the Internet to show what you have in mind. I'd be interested
in seeing if the underlying concept could be adopted by the
things that are part of the FreeBSD documentation.

One thing to keep in mind:

When we are talking about FreeBSD documentation, there is the
documentation concerning the base system, the OS itself. This
documentation is maintained by the FreeBSD team. It consists
of the man pages, /usr/share/doc content, the FreeBSD website
with the FAQ and the Handbook.

Additional software brings its own documentation. Some place
text and HTML documentation in /usr/local/share/doc, some
have good man pages (e. g. mplayer, opera, xmms), others
do not have any of such documentation (e. g. firefox,
thunderbird, any KDE program). Instead, some have local HTML
documentation available locally, others point the user to
a web site, a wiki, or something the like. Those 3rd party
applications choose the kind of documentation _they_ think
is useful for their target audience.



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

Would _you_ send statements like yours to a business list?
With which results other than: "Dear Sir, please be more
specific on your problems so we might help you. For this
information, you've been charged $19.95. Thank you." :-)



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

But the claims HAVEN'T been stated professionally. You didn't
bring _one_ example, not for "unprofessional" documentation,
not for "professional" documentation. You're missing the basic
structure of a professional argumentation, which consists of making
a statement or a claim, then offering arguments that backup the
claim, and additionally bring examples for those arguments.



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



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20110828050926.4e7d0389.freebsd>