From owner-freebsd-doc Sun Jan 7 20:40:24 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id UAA11704 for doc-outgoing; Sun, 7 Jan 1996 20:40:24 -0800 (PST) Received: from time.cdrom.com (time.cdrom.com [192.216.222.226]) by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id UAA11699 for ; Sun, 7 Jan 1996 20:40:19 -0800 (PST) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.6.12/8.6.9) with SMTP id UAA21685 for ; Sun, 7 Jan 1996 20:39:58 -0800 To: doc@freebsd.org Subject: How do folks feel about legitimizing the `style split' in our docs? Date: Sun, 07 Jan 1996 20:39:58 -0800 Message-ID: <21683.821075998@time.cdrom.com> From: "Jordan K. Hubbard" Sender: owner-doc@freebsd.org Precedence: bulk "What the hell is he talking about?" they ask. I'm talking about our long-standing problem with having docs submitted in one of two fairly different styles: 1 "How to do this ..." 2 "How this work works ..." Contrast the difference between a driver's manual ("when you see a red light, STOP!") and an owner's manual ("If you open your hood, you'll a collection of hoses and mysterious chunks of metal - this is how they work and how to fix them when they stop"). Both can be extremely valuable during the period where you own and operate your car, but few would argue that there are many instances when they'd both be used at the same time, or even necessarily by the same people. However, despite the fact that much is also true for operating systems documentation, we've not seen fit to make two books out of it. Instead, we've smashed beginner's guides and expert docs together, resulting in The Handbook. If you try to read it from start to finish, you'll be presented with a bewildering array of stylistic twists and turns as you leave one author's section and move into another's. I would argue that this is not necessary, nor do we need to split the handbook in half. What I would argue for instead is a further level of subcategorization for every major topic, looking something like this: Subject Heading: E.g., you might have something like: 1.2. Network communications with SLIP Contributed by . SLIP is a serial point-to-point protocol for allowing remote hosts to speak TCP/IP to one another over dialup or hardwired links. It use has been largely superceded by PPP, but there are still situations where SLIP is useful. 11.2.1. How to set up SLIP 11.2.2. How SLIP works And the reader would have three `touchpoints' on the page. The intro if they have no idea what SLIP is ("am I even interested in this?"), the `How To' choice if they're definitely interested and need to know how to actually do it step-by-step, and the `How it works' choice if they're more interested in knowing how it all works (and possibly because they don't want step-by-step, they just want to know which parts of the system are "reponsible" for the feature in question). I have the feeling that if we could sweep large sections of the handbook into one category or the other, it would both make the whole thing a lot more readable, and it would point up (through the empty sub-sections) just where we were deficient in howto or hacker documentation. Comments? John, would something like this conflict significantly with your proposed reorg? Jordan