[rfc-i] What the text version is used for (was Re: The <tt> train wreck)
daedulus at btconnect.com
Wed Aug 25 04:59:25 PDT 2021
On 25/08/2021 02:13, Michael Richardson wrote:
> Carsten Bormann <cabo at tzi.org> wrote:
> Yes, the descriptions. It's a disaster coordinating what's in the YANG
> description, and what's in the document, and keeping them in sync. How much
> detail do you put in each part?
I keep forgetting the obvious:-(
The YANG module be it 5 pages or 50 is a separate document. It MUST be
plain text that can be extracted and circulate as an independent
document. The descriptions, the references, the URL and so on must make
sense when it is not part of an RFC. The descriptions must tell the
user what an object is with a reference to where more can be found,
sometimes the 'mothership' RFC, usually not.
My take is that it is like documenting code, the description are what a
good programmer places in the code with the rest of the RFC providing
context, objectives, options rejected and so on.
The issue is how to reference into this plain text be it for a query,
comment, erratum and so on. As I said before, YANG is not structured
the way SMI is so a reference to a leaf may take 10 or so lines of YANG!
Comment lines, which good authors use (as with code), are more compact
(if a little bit too free form).
> Michael Richardson <mcr+IETF at sandelman.ca> . o O ( IPv6 IøT consulting )
> Sandelman Software Works Inc, Ottawa and Worldwide
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
More information about the rfc-interest