From owner-freebsd-questions@FreeBSD.ORG Sun Aug 28 03:09:29 2011 Return-Path: Delivered-To: freebsd-questions@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id C4C60106566B for ; Sun, 28 Aug 2011 03:09:29 +0000 (UTC) (envelope-from freebsd@edvax.de) Received: from mx01.qsc.de (mx01.qsc.de [213.148.129.14]) by mx1.freebsd.org (Postfix) with ESMTP id 6F53C8FC12 for ; Sun, 28 Aug 2011 03:09:29 +0000 (UTC) Received: from r56.edvax.de (port-92-195-72-156.dynamic.qsc.de [92.195.72.156]) by mx01.qsc.de (Postfix) with ESMTP id E01F73CC57; Sun, 28 Aug 2011 05:09:26 +0200 (CEST) Received: from r56.edvax.de (localhost [127.0.0.1]) by r56.edvax.de (8.14.5/8.14.5) with SMTP id p7S39QNZ001946; Sun, 28 Aug 2011 05:09:26 +0200 (CEST) (envelope-from freebsd@edvax.de) Date: Sun, 28 Aug 2011 05:09:26 +0200 From: Polytropon To: Evan Busch Message-Id: <20110828050926.4e7d0389.freebsd@edvax.de> In-Reply-To: References: <16851_1313817220_4E4F4284_16851_6517_1_D9B37353831173459FDAA836D3B43499C521886E@WADPMBXV0.waddell.com> <20110825043208.fe201707.freebsd@edvax.de> Organization: EDVAX X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Cc: "freebsd-questions@freebsd.org" Subject: Re: A quality operating system X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Polytropon List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 28 Aug 2011 03:09:29 -0000 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 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, ...