From owner-freebsd-questions@FreeBSD.ORG Thu Aug 25 02:32:11 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 BACA8106564A for ; Thu, 25 Aug 2011 02:32:11 +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 6A2528FC14 for ; Thu, 25 Aug 2011 02:32:11 +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 BC5393D563; Thu, 25 Aug 2011 04:32:09 +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 p7P2W9MC073403; Thu, 25 Aug 2011 04:32:09 +0200 (CEST) (envelope-from freebsd@edvax.de) Date: Thu, 25 Aug 2011 04:32:08 +0200 From: Polytropon To: Evan Busch Message-Id: <20110825043208.fe201707.freebsd@edvax.de> In-Reply-To: References: <16851_1313817220_4E4F4284_16851_6517_1_D9B37353831173459FDAA836D3B43499C521886E@WADPMBXV0.waddell.com> 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: Thu, 25 Aug 2011 02:32:11 -0000 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 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, ...