ietf-nntp Command description layout

[Russ Allbery]

Clive D W Feather <clive at demon.net> writes:

> I think it would aid the eventual user of this document if there was a
> slightly more formal structure. What I'm thinking of is that every
> command has three numbered subsections:

As someone who's looking at the prospects of needing to write up a bunch
of command descriptions for all of the extensions that INN implements at
present, I think a more formal structure is an excellent idea.  I'd love
to have a standard layout for describing NNTP commands that can be used
for all subsequent extensions.

I only have one problem to point out:

>     X.1 Description
>         Gives an informal description of the command and its specific
>         responses. Certain specifics would be deferred to X.2.
>     X.2 Usage
>         Gives the formal syntax, lists all the responses, defines the
>         meaning of any parameters for both command and response, and
>         notes when the command is not streamable.

I think it would make it unnecessarily hard to write the description if
one couldn't easily reference the parameters of the command (since that
was deferred to the Usage section).  Perhaps it would be better to put the
Usage section first?  It's fairly short and provides a decent summary of
what's going on, and that way the description could reference all of the
details of the usage.

This (usage first, including responses, then description, then examples)
is the layout used by the IMAP specification, and I found it fairly
readable there.

> Do people think this is worth doing ? If so, Stan, I'm willing to do
> much of the actual work if you'll tell me how to provide new text.

I really do think that the proposed text reorganizations and the
formalization of the layout of command descriptions is worth doing.  I
have to admit that I find the current document less than ideally readable
just because of the formatting, and it seems like that would be worth
fixing before release as an RFC just to save small amounts of time for the
thousands of people who will be reading it down the road.

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>