Date: Mon, 18 Feb 2002 20:13:22 -0500 (EST) From: mwlucas@blackhelicopters.org To: FreeBSD-gnats-submit@freebsd.org Subject: docs/35098: NFS chapter simultaneously sucks and blows Message-ID: <200202190113.g1J1DMg12354@blackhelicopters.org>
index | next in thread | raw e-mail
>Number: 35098 >Category: docs >Synopsis: NFS chapter simultaneously sucks and blows >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Mon Feb 18 17:20:01 PST 2002 >Closed-Date: >Last-Modified: >Originator: Michael Lucas >Release: FreeBSD 3.5-STABLE i386 >Organization: None >Environment: Today's -doc tree >Description: Per our discussions at the BSDCon BoF, here's my stab at a "copy edit" for the NFS chapter. Unfortunately, I'm too busy dealing with my book mss. to clean this up myself, so I have no option but to send it in as a PR. If this is deemed useful, I will keep it up until the word "Lucasify" enters the FreeBSD DocProj vocabulary. This is presented in the spirit of "give a committer patches, and the chapter will be fixed. Give the committer feedback, flames, and general sarcastic abuse pointing out his flaws, and the committer will never make that same mistake again." :) >How-To-Repeat: read the NFS chapter >Fix: Summary: too many words, and not the right ones either! Suggestion to fix this chapter: print it out. Get a red pen. Read the chapter aloud. Yes, in a voice loud enough to be heard. Listen to the sound of your own voice. If something sounds odd or verbose, or if you cannot read a sentence aloud, mark it for evaluation when you're done. sentence 2: "you" don't share directories. Your system shares directories. (Of course, perhaps your wetware supports NFS; I edited that out of my personal kernel.) This sort of thing is a good candidate for a global search-and-destroy mission. "via the network they are attached to." As opposed to the network that they are *not* attached to? How about just "via the network."? bullet 1: "...and still remain accessible to everyone on the network." Of course, these files are accessible even if the workstations had disks. This explanation should be tightened, as B either does not really follow from A or is painfully obvious. bullet 2: "that is" is unnecessary and verbose. "Home directories exported via NFS can be available to their user from any machine" would be better, but this can and should be made tighter and more specific still. bullet 3: this sentence needs some sort of a comma. Try reading it aloud in one natural breath. (deep breaths don't count.) Also, you aren't exactly "eliminating the need for extra hardware," more "reducing hardware needs." We all know that there is no extra hardware, and most systems ship with floppy/CDROM today. 17.4.1 sentence 1: side, side, side. Redundant. The server, the client, period. sentence 2: ambiguous "it". sentence 3: "client" "server side". neither should have side, or both should have side. Recommend cutting "side." "The server has to be running the following daemons:" tighten, i.e.: "NFS servers run the following daemons:" Easy passive voice elimination. Hmmm... then we have "daemon description" in bold, followed by a list. The "client side" description below runs right into it, almost as if it is part of the same list. Hard to sort out, blech. The description of nfsiod is somewhat obtuse. "async I/O"; why is this important to a beginner? Also, why is Daemon capitalized? This daemon serves requests from the NFS server, but why is it running on the client? Does the server ask the client for things, or does the client as the server? WTF? 17.4.2: "Luckily for us, on a FreeBSD system this setup is a snap." Uh, these are pretty strong words here. Are we really, *really* ready to back them up? Not with this chapter, we aren't. para 2: "make sure you have"... variable settings. Oh, I have these all right. I typed them in at the command line. That's where you want them, right? Oh, they go in /etc/rc.conf? Well, why didn't you say so? para 3: "mountd is automatically run" -> "mountd runs automatically" We describe the various nfsd options, but why are these options important? If we don't say why these are important, why mention them? And what are the settings from /etc/defaults/rc.conf? Why mention settings that are the default, is this the FreeBSD docproj standard? If so, the Handbook needs to be edited to include this in all the other places. (The other option, of course, is that we want to confuse our reader to maintain our highfalutin' 133t image.) para 4: "On the client, make sure you have"; again, have where? Also, nfs_client_flags is set by default in /etc/defaults, why explicitly mention it here? So we come to /etc/exports. The most frequently screwed-up portion of NFS setup isn't important enough to rate its own section heading? "The last configuration step requires that you create a file called /etc/exports" -> "Last, create /etc/exports." This might be too tight, but what appears is certainly too verbose. Better still, give this section a heading and eliminate the first sentence. "The exports file specifies which file systems..." is a perfectly acceptable first sentence. This sentence could be tightened as well, though. So, we go through and give some examples. This actually doesn't suck too badly. Doesn't making these changes take effect and starting the commands rate its own header, or is this really part of configuring NFS? Should be set aside from /etc/exports at least. "You must restart mountd whenever you modify /etc/exports to make changes take effect. This can be accomplished by sending the hangup signal to the mountd process:" -> "To make changes in /etc/exports take effect, restart mountd." The example shows exactly how to do this; people who know how to restart mountd won't care, while novices don't give a dang about "hangup signals," they just want to know what to type. "Now that you have made all these changes..." We have a sentence that ends in a colon, followed by two sentences that end in a colon. "This can be done one of two ways." We describe one way that it can be mounted, and then describe the way to have this type of mount take place at boot time. What's the second way? Actually, it can only be mounted in one way. Mounts can be done at boot, or manually, but they are actually performed the same way. (This is an example of "can be misunderstood.") 17.4.3: bullet 2: the grammar in the first sentence is so bad, I don't know where to start making fun of it. bullet 3: So, if I drop a CDROM into one machine I'll be ready to go? Shouldn't I, say, set up /etc/exports first? Why is this better than setting up a FTP server on the same machine? 17.4.4 "amd, which is also known as the automatic mounter daemon, is"-> "amd, the automatic mounter daemon, is" amd isn't just for remote filesystems; see 2/2002 Daemon News. "Using amd provides a simplistic alternative to static mounts" -> amd is not simplistic, but it is simple. Also, it isn't an alternative to static mounts, it's an alternative to permanent mounts. If these mounts were permanent, they would be in /etc/fstab. The section on showmount isn't relevant to amd. It is an excellent example to see what is available from a server, and should be listed under the NFS section. Again, why show default amd flags? Are we going to explain all of these, and when to change them? 17.4.5 This whole section is old. Very, very old -- it specifically references ISA cards.. And it doesn't mention the more common issues of NFS mounts, which are different types of support on the server and client. Some enterprising person could dig through the freebsd-net archives and create a list of "reasonable options to use when mounting/exporting from/to other OSs." You could list Solaris 2.6, 2.7, 2.8, AIX 3, AIX 4, Linux 2.0, Linux 2.2, Linux 2.4, and so on. While you're at it, FreeBSD's default NFS mounts are awful. They are the most widely interoperable, but they're awful for more modern systems. We should document the better options. Again, these are available from the freebsd-net archives. >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the messagehelp
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200202190113.g1J1DMg12354>