Skip site navigation (1)Skip section navigation (2)
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>