This series started by discussing the history of the IETF and some of the tools you might use to build submissions to the IETF process. This, the second, post, will consider document formatting and two of the (sometimes) more difficult sections of an IETF draft to fill in.
Formatting
Just using one of the acceptable file formats—XML is, again, preferred—isn’t enough, though. To make RFCs more consistent, and hence more searchable and readable, the IETF requires all submissions to follow a specific format.
When I first began writing RFC drafts in XML, I looked around for an official Document Type Definition (DTD) for RFC drafts, but I couldn’t find one that supported Dreamweaver or VSC. While the recent SVG file in the IETF’s GitHub repository might work, I find it’s easier just to start with one of the standard templates.
The basic document has three elements, called (oddly enough) the front, the middle, and the back. The front carries most of the metadata about the document, including the authors, publication date, expiration date, intended document state, working group, copyright information, and abstract. The middle contains the main part of the draft itself, describing proposed changes to a protocol, a best practice, etc. The back contains any appendixes and references.
Most of the information required and formatting rules are straightforward. There is plenty of information online about how to build diagrams, how to handle references, and how to handle intellectual property. RFC7322 describes the basic formatting and sections of an RFC draft, and this document provides instructions to authors from the RFC editors.
Just because I’m not going into detail on these things doesn’t mean you don’t need to pay attention to them!
A little more detail is useful in other cases; what might seem straightforward sometimes isn’t.
Authors, Contributors, And Acknowledgements
The generally accepted meaning of author is someone who contributes significant text to the draft. A contributor contributes text or ideas to the draft. Someone who suggested ideas or text is acknowledged. These definitions are not well adhered to, however—they could have different meanings for every document.
Author inflation is a well-known problem in the IETF.
Documents sometimes have a lot of authors because they describe complex solutions or protocols requiring a lot of input from different people. Hard problems require complex solutions, and complex solutions are often best solved in teams, rather than by individuals.
Documents can also have a lot of authors to give them more “weight” in the community. Having authors from multiple vendors implies widespread implementation. Having authors from multiple operators implies widespread deployment. Having an author who is a “though leader” implies “smart folks think this is a good idea.”
Sometimes authors are included “just for ego,” or “if you support my idea, I’ll support yours.”
Regardless of how many authors are included on a draft, the IETF limits published documents to five authors. Documents with more than five authors are often converted to “editor/contributor,” where two editors are chosen to “manage the text,” and the authors are moved to the role of contributors. Sometimes the editors will be the “lead authors.” Other times editors will be chosen just because they have the time to engage in the process, or because they are better writers—or even because they are neutral in some disagreement among the authors.
Working Groups And Areas
Which working group should you submit your draft to? Sometimes the answer to this will be obvious—but other times, the answer might be “none of the above.” For instance, if you’re working on some new idea for BGP (please don’t, BGP is already overloaded), there are at least three working groups you might want to consider.
If the draft is related to BGP security, then you might want to submit it to the SIDR-OPS working group. If it’s related to a service running on top of BGP, the BESS working group might be best. If, however, your draft relates to the basic operation of BGP, you probably want to submit it to the IDR working group.
The hard way of making this decision is carefully reading each of the working group charters, looking at other documents the working group is working on, and think deeply about whether your draft fits into this scope of work. But you might want to take an easier path because charters can be changed, the scope of working groups is often flexible, and working groups can overlap.
Narrow the field of possible working groups down to two or three. Pick the one that seems the most likely to be interested in your draft. Just because a draft is “in scope” doesn’t mean a working group will be interested in the idea, and just because a draft is “out of scope” doesn’t mean a working group won’t be interested in the idea.
Once you’ve narrowed things down to one or two working groups, email one of the working group chairs and ask if they think the working group would be interested.
This is one of those places where many folks—especially first-time authors—make the mistake of thinking “if an idea is good, people will be interested in it.” The IETF, like all other human organizations, is built largely on personal relationships. You cannot just hit “publish,” include a target working group, and expect your draft to progress towards an RFC number.