From owner-freebsd-doc Mon Jan 8 08:07:45 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id IAA17754 for doc-outgoing; Mon, 8 Jan 1996 08:07:45 -0800 (PST) Received: from fslg8.fsl.noaa.gov (fslg8.fsl.noaa.gov [137.75.131.171]) by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id IAA17748 for ; Mon, 8 Jan 1996 08:07:39 -0800 (PST) Received: by fslg8.fsl.noaa.gov (5.57/Ultrix3.0-C) id AA27238; Mon, 8 Jan 96 10:07:38 -0600 Received: by emu.fsl.noaa.gov (1.38.193.4/SMI-4.1 (1.38.193.4)) id AA10265; Mon, 8 Jan 1996 09:07:36 -0700 Date: Mon, 8 Jan 1996 09:07:36 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) Message-Id: <9601081607.AA10265@emu.fsl.noaa.gov> To: jkh@time.cdrom.com Cc: doc@freebsd.org In-Reply-To: <21683.821075998@time.cdrom.com> (jkh@time.cdrom.com) Subject: Re: How do folks feel about legitimizing the `style split' in our docs? Sender: owner-doc@freebsd.org Precedence: bulk >>>>> "Jordan" == Jordan K Hubbard writes: Jordan> "What the hell is he talking about?" they ask. Uh oh ... another Jordan diatribe. At least it'll be an amusing read :-) (Really, I'm kidding!) Jordan> I'm talking about our long-standing problem with having Jordan> docs submitted in one of two fairly different styles: Jordan> 1 "How to do this ..." Jordan> 2 "How this work works ..." Yes, I'll agree with this, to a point. There are some aspects of using and administrating an operating system where education about how it works is a lot more useful than step-by-step instructions on how to do something. Teaching someone how to set up an /etc/exports file goes quite smoothly with: ``1. Using your favorite text editor, ...'' Debugging why the fifth mountd request gets refused after hanging for ten minutes but only if there are two simultaneous X servers is definitely not served by ``1. Ummm, let's see, where could we begin?'' Jordan> Instead, we've smashed beginner's guides and expert docs Jordan> together, resulting in The Handbook. If you try to read Jordan> it from start to finish, you'll be presented with a Jordan> bewildering array of stylistic twists and turns as you Jordan> leave one author's section and move into another's. True. This is part of the reason why Don Knuth's _TeXbook_ fails. Despite the so-called dangerous bends, the beginner cannot determine how to make a report document with tables without skipping around a lot. The expert cannot determine why a marginal note is adding vertical glue to the main vertical list without skipping around a lot. Jordan> I would argue that this is not necessary, nor do we need Jordan> to split the handbook in half. What I would argue for Jordan> instead is a further level of subcategorization for every Jordan> major topic, looking something like this: Jordan> Subject Heading: Jordan> Jordan> Jordan> I like it. But the printed manual really should keep this material separate, lest we make the same TeXbook mistake. We should be able to identify SGML-wise which topics should end up in which book. Jordan> Comments? John, would something like this conflict Jordan> significantly with your proposed reorg? I must've missed the proposed reorg ... what's that all about? -- Sean Kelly NOAA Forecast Systems Laboratory, Boulder Colorado USA My girlfriend asked me how long I was going to be gone on this tour. I said, "the whole time." -- Steven Wright