Date: Sat, 17 Mar 2001 12:15:30 -0800 From: richard childers <fscked@pacbell.net> To: David Johnson <djohnson@acuson.com> Cc: Ted Mittelstaedt <tedm@toybox.placo.com>, freebsd-questions@FreeBSD.ORG Subject: Re: documentation issues generally Message-ID: <3AB3C5E2.729447AF@pacbell.net> References: <010301c0ae3e$577a1d80$1401a8c0@tedm.placo.com> <3AB25AA3.CFD6AC22@acuson.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Often, the documentation I write is process-oriented; it is not about a topic in general but about how to do something specifically, using a combined set of (often open source) tools. For instance, when working at Hambrecht & Quist, we used Red Hat Linux to drive something called a 'datawall', if memory serves me correctly; it was a bank of LEDs with the ability to format and display text; it was used to replace an older whiteboard-based system, by which traders were apprised of information they needed to know; unfortunately, the trading floor was now larger than the sphere of influence of a single whiteboard and maintaining two whiteboards in sync proved problematic. Developers latched upon the 'datawall' and chose Red Hat Linux as the platform of choice. They put the platform outside the firewall so that the datawall developer on the East Coast could reach the server and prototype board, on the West Coast. (No comments, please; it was at this point that I became involved. Rest assured that nothing but source code was copied from the system and that the original platform was nuked.) I was tasked with creating the production environment. The most critical part of the entire process was documenting what I did; because we anticipated the possibility of needing to reproduce one of these systems in the future, remotely, perhaps ... and because we were going to distribute these servers to New York and Boston as well as San Francisco, and I wanted to be able to use the consistency of the systems, to facilitate diagnosis of possible problems. I walked through the Red Hat installation sequence a few times before I got started, just to make sure I knew what options existed (something that I also do with FreeBSD or any other OS, each time I get a new release). Each of the systems needed to be exactly identical because otherwise we, in Operations, would get involved in a sniping war with clueless developers about whether problems encountered, down the road, were due to inconsistent Linux installations ... network problems ... problems with the NT-based database that fed this thing ... or problems with the datawall driver, itself. Guess which one would come first. /-: What I ended up with was very usable. It included numbered steps describing briefly what was to be done; the modularity of each operation was one command-line interaction. Each step included an example of what you typed ... and what you would see in response; after that came a paragraph or two expanding on what had just been done, for those new to UNIX (after all, we were designing for worst-case scenarios; one never knows when one will walk in front of a bus and need to be hurriedly replaced) ... and different fonts and whitespace offsets were used, as needed, to emphasize the summary, example, and narrative portions of the text. It was readable and it was pretty, too (but, then, I used to design fonts & logos, in a previous life, so I could be accused of having a warped perspective :-). It was all done in plain HTML; nothing fancy. It was designed to be printed out and filed against use after an earthquake, as well as accessed from our IT web server, inhouse. I've done the same thing for Solaris, and other operating systems - yes, even NT - detailing exactly how I wanted Solaris to be installed; and why. I've found that that second element - the narrative - is very important when one is issuing instructions to less-experienced UNIX administrators, by the way; it turns what might be a point of religious contention into an opportunity for making good friends, because it turns what might otherwise come across as a directive from a bossy and opinionated airhead, into a thoughtful exchange between the author, and their reader(s), where not only is there a What, but also a Why; and an invitation extended to all readers to provide feedback to the author (common in the commercial world, less so in the corporate world). Unfortunately, it's hard for a software developer to anticipate all of the uses that their software will be put to; and it's even harder for them to view the description of the process from the point of view of a beginner (shall we call it 'beginner's mind'?*). I think documentation that is process-oriented, user-friendly, deterministic (IE, if you follow these instructions you will reach this point, unequivocably), and includes a friendly explanation using simple words (IE, doesn't use 'unequivocably' :-), is critical to FreeBSD's future success. Perhaps 'The FreeBSD Cookbook' is a good title for such a practical document; the load could be distributed across the interested authors, with an editor acting as central coordinator, and the results being published in a cost-effective looseleaf plastic ringbound edition, much like USENIX used to publish the BSD 4.2 manual set, lo, a decade or so ago (and who knows, maybe they still do). Those manuals were collections of reprints of papers by the authors of the separate pieces of software; Bill Joy describing how to install it, Kirk McKusick describing how to tune and use the UNIX Fast File System; there was no one author, only a collection of papers by different specialists. Really, the *installation* of FreeBSD, the *operation* of FreeBSD, and the *application* of FreeBSD as a platform, supporting an application-oriented infrastructure, are really separate topics, that appeal to serparate audiences; the separation of these three topics into separate volumes would, perhaps, lead to greater market penetration (and I can't believe I just said that; gotta go wash my mouth out :-). (Insert sound of competing publishers scribbling notes feverishly :-) -- richard * Zen pun. (-: David Johnson wrote: > Ted Mittelstaedt wrote: > > > I disagree with this. Rather, the problem is that programmers usually > > dislike > > "wasting time" on writing documentation. All of them that I've worked with > > are more than happy to have someone else do it. But, I've not sensed that > > anyone I've worked with has "looked down" on what I'm doing. > > It's not that they consider it "wasting time", it's just that it's pure > drudgery. I've written documentation for my own programs, and am > currently helping with docs for KDE. It's not fun. It's boring. The > developers should be the ones writing the docs, since they know the > software the best, but they will probably be the ones least likely to > enjoy writing it. > > David > > To Unsubscribe: send mail to majordomo@FreeBSD.org > with "unsubscribe freebsd-questions" in the body of the message -- Richard A. Childers Senor UNIX Administrator fscked@pacbell.net (email) 415.664.6291 (voice/msgs) # Providing administrative expertise (not 'damage control') since 1986. # PGP fingerprint: 7EFF 164A E878 7B04 8E9F 32B6 72C2 D8A2 582C 4AFA To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?3AB3C5E2.729447AF>