Date: Wed, 18 Sep 1996 17:05:10 -0500 (EST) From: John Fieber <jfieber@indiana.edu> To: Nathan Wittich <User@cdsnet.net> Cc: doc@freebsd.org Subject: Re: spaghetti documentation Message-ID: <Pine.BSI.3.95.960918163819.25868C-100000@fallout.campusview.indiana.edu> In-Reply-To: <31C17523.788A@cdsnet.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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 ================
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSI.3.95.960918163819.25868C-100000>