From owner-freebsd-doc Wed Sep 18 15:05:23 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id PAA19576 for doc-outgoing; Wed, 18 Sep 1996 15:05:23 -0700 (PDT) Received: from fallout.campusview.indiana.edu (fallout.campusview.indiana.edu [149.159.1.1]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id PAA19549 for ; Wed, 18 Sep 1996 15:05:19 -0700 (PDT) Received: from localhost (jfieber@localhost) by fallout.campusview.indiana.edu (8.7.5/8.7.3) with SMTP id RAA25969; Wed, 18 Sep 1996 17:05:10 -0500 (EST) Date: Wed, 18 Sep 1996 17:05:10 -0500 (EST) From: John Fieber To: Nathan Wittich cc: doc@freebsd.org Subject: Re: spaghetti documentation In-Reply-To: <31C17523.788A@cdsnet.net> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk On Fri, 14 Jun 1996, Nathan Wittich wrote: > But about your online documentation, though, It's > as much of a challenge to understand and find what you're looking for as > reverse-compiling basic that was originally spaghetti. Welcome to Unix! Improving the documentation in a substantial way is a monumental task, especially when nobody is being coerced with money to do it. :) The big difference between traditional unix documentation and the stuff Microsoft (and others) put out now is that the former documents program functionality while the latter documents user tasks. For the beginner, task documentation is more useful, for the veteran, tool documentation is essential. This difference mirrors the design philosophies of the respective systems. Small tools that the user can combine in numerous ways to accomplish numerous tasks, or large software designed to accomplish a specific task or set of tasks. The former is hard to document in a task oriented fashion, it has a reputation for being hard to learn, but very powerful. It is easy to create task oriented documentation for the latter, but there is no documentation to fall back on if your task was not anticipated by the software designer or the documentation writer. What is better? It depends entirely on the context. The tutorials, the FAQ and the Handbook are all attempts to bring some task oriented documentation on the scene. However, particularly in the case of the Handbook, they will always be somewhat disjointed and incoherent as a whole unless someone can invest the huge amount of time required to play full time editor. Unlike hacking on code, this is not a task that can be easily divided up among a team with success. -john == jfieber@indiana.edu =========================================== == http://fallout.campusview.indiana.edu/~jfieber ================