Ron Bonica review - document too long

[AdrianFarrel]

Ron was asked to do a review in the context of PROBE. He wrote:

I think this is a very important draft. However, its readership will decline as a function of its length.

It might be best to provide a list of questions that an author should consider:

• Question 1
• Question 2
• Question n

If the answers to any of these questions are non-trivial, they should be provided in a sub-section of the operational considerations section.

If the operational consideration section is empty, it can be omitted.

The document probably should exceed 15 pages.

[xorrkaz]

As a "fun" exercise, I took the text version of the draft from my interop-rewrite branch (after rebasing to main) and asked Gemini the following:

Attached is an IETF internet draft revision RFC5706 with modern management and operational considerations. This draft is packed with useful advice, but it has received feedback from the internet community that it is too long. Specifically,

I think this is a very important draft. However, its readership will decline as a function of its length.

It might be best to provide a list of questions that an author should consider:

Question 1
Question 2
Question n

If the answers to any of these questions are non-trivial, they should be provided in a sub-section of the operational considerations section.

If the operational consideration section is empty, it can be omitted.

The document probably should exceed 15 pages.

Taking that feedback into account, provide the following:

• Provide a set of core questions protocol designers in the routing and applications spaces should consider
• Create a new internet draft in kramdown format with those questions and the relevant sub-sections

Finally, for the authors' consideration, offer suggestions on how we might ourselves shorten the document by removing text, rephrasing parts of the document, or moving text to appendices.

Attached is what it produced in terms of a revised I-D. The intent of this was to produce something for discussion and provide an alternative representation of the existing work.

draft-rfc5706bis_ai.txt

[xorrkaz]

The other artifact the AI spit out was these suggestions. Some of which are useless, but others are useful and likely things we wanted to do anyway.

Suggestions for Shortening the Original Document (draft-opsarea-rfc5706bis.txt)

To significantly reduce the length of the original document and improve its readability and adoption, consider the following strategies:

1. Adopt a Question-Based Structure:

   • Refactor the detailed prose of Sections 4, 5, and 6 into a concise list of high-level questions, similar to the "Core Questions" section provided in the new draft above.
   • Instruct authors that if the answer to a question is non-trivial, they should provide the detailed explanation in a sub-section within their "Operational Considerations" section, rather than having the guidelines document itself provide exhaustive examples for every scenario. This shifts the burden of detail to the specification being written.

2. Create a Separate "Companion Guide" or "Best Practices" Document:

   • Move much of the extensive explanatory text, detailed examples (e.g., BGP flap damping, RSVP Router Alert, TCP RTT/RTTVAR, cryptographic key handling, ACL reordering, specific MIB module issues), and in-depth discussions of why certain considerations are important into a separate, more detailed companion document.
   • The main RFC (rfc5706bis) would then serve as a high-level reference, pointing to the companion guide for deeper understanding and specific examples.

3. Externalize the "Checklist":

   • The document already mentions [CHECKLIST]. Fully separate this into a standalone, living document (e.g., on GitHub) that can be updated more frequently than an RFC. The main RFC should simply reference this checklist as a tool for reviewers and authors.

4. Streamline Terminology:

   • Reduce the "Terminology" section to only the most essential terms directly used and defined within the concise guidelines. For terms that are well-defined in other RFCs, simply provide the reference without repeating the full definition (e.g., for "Anomaly," "Cause," "Fault," "Problem," "Probable Root Cause").

5. Condense General Introduction and Scope:

   • Make the "Introduction" and "This Document" sections more direct and succinct, focusing on the purpose and scope of the guidelines without extensive background narrative.

6. Summarize Management Technologies:

   • In "Available Management Technologies" (Section 5.1), instead of describing each technology (SNMP, NETCONF, RESTCONF, IPFIX, syslog), briefly state that IETF provides various standardized management protocols and refer to a dedicated overview document like [RFC6632] for details.

7. Refer to Dedicated YANG Guidelines:

   • For detailed YANG Data Model Considerations (Section 5.3.2) and Information Model Design (Section 5.3.1), primarily refer to the existing and evolving YANG authoring guidelines like [I-D.ietf-netmod-rfc8407bis] rather than duplicating extensive advice within this document. Keep only the high-level questions about what type of YANG model to consider.

8. Selective Informative References:

   • Review the "Informative References" section and drastically reduce it. Include only references directly cited in the concise text or those absolutely foundational to the understanding of the core guidelines. Many current references are for specific examples or deeper dives that would be more appropriate for a companion guide.

9. Compact Acknowledgements and Contributors:

   • While important, these sections can be formatted more compactly to save space.

By implementing these suggestions, the draft-opsarea-rfc5706bis.txt could be transformed into a highly readable and actionable document well within the 15-page target, making it more effective for its intended audience.

[bclaise]

Another possibility is to re-read the draft and see which (educational) sections can be removed or moved to the appendix.

[xorrkaz]

From Alvaro: Consider putting the question list as an appendix referencing the relevant sections. Refer to the appendix up front for those that want to jump the checklist.