Subject: Re: Several reminders

From: Stuart Cheshire <[email-masked]>
Date: Fri, 24 Aug 2001 18:14:59 -0700

>I have some reminders to send along...
>
>WG last calls have been posted for all of the following docs; please be 
>sure to respond with comments by the end of the last call period (8/24):

The comments below apply to concat-01.txt, domsearch-05.txt, csr-04.txt 
and ddns-resolution-02.txt.

References are supposed to be an addition to written prose, not a 
substitute for it. References are there so that when an inexperienced 
reader doesn't understand a statement you make, they know where to look 
for more information. References are there so that when an *experienced* 
reader doesn't *agree* with a statement you make, they can find upon what 
prior work you are basing your assertion.

You should be able to delete the references from a piece of text and have 
it still make sense to an experienced reader. Put another way, the reader 
shouldn't have to keep flipping to the back of the document to understand 
what a sentence is saying. There are several places in these drafts that 
fail this test. For example:

>The DHCP packet format is based on the BOOTP packet format	defined in [4].

Without the list of references to hand, this is not a complete sentence.

You can fix this two ways:

1. Delete spurious words:

>The DHCP packet format is based on the BOOTP packet format [4].

2. Write complete prose:

> The DHCP packet format is based on the BOOTP packet format	defined
> in the Bootstrap Protocol specification [4].

I also prefer semidescriptive references instead of numeric references so 
an experienced reader can recognise the reference in context, instead of 
having to flip to the back of the document to find out what "[4]" means:

>The DHCP packet format is based on the BOOTP packet format [RFC950].

RFC950? Internet Standard Subnetting Procedure, by Mogul & Postel? I 
don't think that's the document that was intended to be referenced by 
[4]. I think RFC951 is the one that defines the BOOTP packet format.

I think I've made my point why descriptive references are more useful 
than anonymous numbers.

Some other examples of sentences that make no sense until you flip to the 
back of the document to fill in the missing words:

>multiple options may be used, as described in [ ].

>searchstrings in the searchlist are concatenated and encoded
>using the technique described in section 4.1.4 of [ ].

>Thus the compression method described in [ ] is both useful
>and likely to be effective.

>This maintains consistency with section 4.1 of [ ].

>DHCP servers sending this option MUST use the technique described in [ ]

>FOr this purpose, a DHCID RR, described in [ ], is used to associate
>client identification information with a DNS name and the A or PTR
>RR associated with that name.

Stuart Cheshire <[email-masked]>
 * Wizard Without Portfolio, Apple Computer
 * Chairman, IETF ZEROCONF
 * www.stuartcheshire.org

---

From: Ted Lemon <[email-masked]>
Date: Sat, 25 Aug 2001 11:04:38 -0400

> substitute for it.

Actually, this is not true, and is a dangerous idea.   If I define the
format of something that's authoritatively defined elsewhere in my own
draft, and I make a mistake in transcribing or paraphrasing the
authoritative source, this is likely to create interoperability
problems when someone doesn't refer to the source.   So I _must_ refer
to the authoritative source, and _must not_ paraphrase it.

			       _MelloN_