search

rfc-editor / draft-rpc-rfc7322bis

Contains the draft of the RFC Style Guide
11 stars 2 forks source link

guidance on when to create indexes #14

Open ajeanmahoney opened 1 year ago

ajeanmahoney commented 1 year ago

RFC 7322 does not provide guidance on indexes. Perhaps the update should say that an index is an optional section that is better suited for documents over 100 pages and that it should be built manually (that is, the placement of iref tags should be determined by the author rather than by a script) with the reader's interests in mind. In general, documents should be organized such that the table of contents provides useful, descriptive links for the reader (maybe this guidance can also go on authors.ietf.org).

ajeanmahoney commented 1 year ago

Tooling: xml2rfc automatically places the index before the Authors Addresses section but after any Contributors section. Is this the best place for an index?

jrlevine commented 1 year ago

I think that the utility of an index depends less on the length of a document than on its structure. If there are concepts or features that appear in multiple sections, an index can help you find all those places. I strongly agree that index terms have to be selected manually. If I just want to find all the places where "flurb" occurs, it's faster to use the search button than to look in an index.

cabo commented 1 year ago

Tooling: xml2rfc automatically places the index before the Authors Addresses section but after any Contributors section. Is this the best place for an index?

I would expect us to make authors and contributors more analogous to each other in future versions of RFCXML. Interspersing an index between the lists sounds broken to me.

I don't have my CMOS with me, but I'd expect an index as the last part of a document, possibly followed only by a colophon (which we don't have any more). (This was once necessary by the indexing process, but has survived.)

jrlevine commented 1 year ago

On the other hand, the author addresses have been at the end of RFCs for a very long time. CMOS section 1.66 says that biographical notes if present usually appear after the index, even though 1.64 says the list of contributors is before the index. In technical papers I read, if addresses are present at all, they're in a footnote at the bottom of the first page.

I think we have bigger fish to fry.