IETF互联网标准写作指南
转自中国教育网络
互联网工程任务组IETF作为一个公开的国际性大型非政府学术与工程组织，致力于互联网相关技术标准的研发和制定。它汇集了与互联网架构和互联网顺利运作相关的网络设计者、运营者、投资人和研究开发人员，其制定的标准深受互联网界的推崇。迄今为止，IETF已经制定了4700多项RFC，包含我们所熟知的TCP协议、IP协议等等，支撑起了整个互联网协议标准。
随着我国互联网相关研究水平的逐步提高，我国已经将提出具有自主知识产权的国际标准特别是IETF RFC作为国家信息领域标准化战略的重要发展方向，国内很多高校、研究机构和企业也已经将参与IETF进行标准化工作作为重要内容。
我们知道，写得好的协议规范能使执行方更好地符合协议的规范、协议测试方获得更明确的可测试陈述、协议购买方与协议用户也会对其性能有更好的了解。然而，由于我国很多研究者对IETF文化涉足不够，即便掌握了互联网最新技术及其发展趋势，提出互联网发展的新标准，也很难写出被IETF广泛认可的RFC。为此，本文专门就此问题，介绍在写作RFC及其草案的过程中，需要注意的一些要领，供相关研究者参考。
事实上，IETF为了规范RFC及草案的书写，已经专门制定了RFC2360“互联网标准写作指南”和RFC2223“RFC写作指导”，讲解了RFC的主要组成部分，并给出了使文章连贯、准确、完整、通俗易懂的要素。协议标准化的更多信息请参见BCP 9/RFC 2026，“互联网标准程序（第三版）”，协议设计的注意事项则在RFC 1958“互联网体系结构原理”中给出。
>>> ASCII图表
由于RFC及其草案往往是采用ASCII码形式的文本文件，因此其中的图表也需要使用ASCII码文本来展示。
1．数据包图表
大多数链路层、网络层与传输层协议都有数据包描述，因此数据包图表对读者来说至关重要。首选的数据包图表是比特编号位于顶端，按网路字节顺序横向排列的一长串字符。
当数据包按字节对齐而不是按字对齐时（即以字节为边界的可变长字段），将数据包图表以字节宽的格式显示。作者可用不同高度的方框安置长短不一的字符，用不规则的框架安置变长的字节。
2．状态机的描述
提出协议行为的一个便捷方法为状态机描述，即协议可由命令、运行、处理得来的一系列状态描述。状态机模型定义了建立一种状态的变量和常量、促成状态转换的事件和来自这些转换的动作。通过这些模型，可以理解任何指定事件的状态转换所导致的协议动态操作。状态转换可以用图表和时间线来详细描述。状态机只作为文本的附属品，永远无法取代规范文本的详细描述。当争议产生时，协议描述永远占优先地位。
使用状态转换图时，用状态弧线连接的方框来表示每种可能的协议状态。作者应在每个弧线上标注促成转换的事件，并用括号标注转换中发生的动作。参见STD 5/RFC 1112。
因为ASCII文本是RFC的首选存储方式，所以只能用简单的图表示，表格则可以概括更复杂或更广泛的状态转换关系。
在状态转换表中，事件纵向列出，状态横向列出，表格代表了状态转换与动作。多个动作按执行的必要性由逗号隔开，状态后的字母代表说明性的脚注。破折号指代非法转换，参见STD 51/RFC 1661。
最后一种方法是时间线。时间线的两端代表交换中的机器，作者随着时间推进（向下）沿着时间线的外部列出机器的状态，在时间线的内部表示了造成状态转换的动作，如下图所示。
安全问题至关重要
作者必须接受其详细说明的协议遭到攻击的现实。他们有义务来说明哪些攻击有可能发生，并应详细说明攻击的性质；如果无法避免在特定环境中的攻击，则要考虑限制协议在该环境中的应用。在尽可能详尽地列出所有可能出现的安全隐患之后，作者必须阐明防御办法，并讨论可用的对策或用户应用协议会产生的风险。
有关安全问题的讨论通常集中在文件的安全问题部分（如最后一节“Security Considerations”）或文件通篇与之相关的部分。后者的优点在于其确保了安全问题是协议的主要部分的地位。可能会有几个安全机制由于多种原因未能采用，例如成本高、执行困难、所给网络环境效率低等。通过列举未采用的机制，作者可以阐明协议相关工作组已对安全问题做出了必要的考虑，同时还可以让使用该协议的用户知道是否有更适合他们特殊需求而未被采用的机制。
协议中的常见问题
协议描述必须说明协议的目的、功能、服务、操作平台、环境及协议运用的注意事项，特别是详细说明该协议的目的与用途，给读者一个立足点，以更好地理解协议。
RFC的写作目的从技术方面到管理方面多种多样，因此写作标准应该划分不同读者群。如果多方读者均出现在文档中，不同读者的不同需求也应加以细分。
与此同时，RFC作者应考虑怎样阐述细节最能达到协议的目的。简明的文章优点在于通俗易懂、较少争议以及协议执行的要求一目了然；缺点在于读者不能充分理解和体会协议背后的深层含义，从而导致执行错误。详细描述的文章可以帮助读者更好地理解协议，但同时也存在缺点，如晦涩难懂、易产生歧义、对于母语非英语的IETF读者来说，存在阅读困难的问题。解决方法是将标准划分为不同部分：一部分简洁概述，另一部分加以解释说明。
一项RFC从开始以RFC草案的形式提出到最后发表，往往需要经过多次修改。保留修改记录对RFC的编辑者或作者来说是非常必要的，作者往往需要说明先前版本与最新版本的不同，包括改变的原因，如执行经验、技术改变、用户需求等。将争议的基本内容写入，有助于防止其再次发生。另外，通过规范一个标准的回应，标准作者可以减小多方讨论产生争议的概率。
协议应清楚描述异常或超出规范行为的操作。针对这一问题，有两种处理方法，分别为删除或采用错误处理机制。作者应对发送方与接受方的行为分别进行详细描述，避免二者产生误解，尤其是对于接受方的描述。
多选项的规范加大了执行的复杂性与被误解的可能性。一种可行的方法是将文档中的协议选项进行单独描述，这能保持主要协议的结构清晰。但无论怎样，文章都要讨论是否应用该选项，及应采用何种方法等。此时作者应描述选项怎样同其他协议一同应用，以及所有选项的默认条件。为了清晰起见，作者应说明何时执行、选择的效果及用户可能面临的问题。
BCP 14/RFC 2119给出了“RFC中的要求级别关键词”。作者在确定协议要求或限制潜在有害行为时，不能偏离这些定义。这些关键术语通常采用英文大写字母的方式，参见STD 3/RFC 1122/RFC 1123。
另外，形式语言表达式可被用来定义复杂的协议概念或数据类型、详细说明数据的值，使规范简单化。作者在运用形式化语言表达式前应考虑几个问题：所使用的形式化语言能否被现有机器进行解析和理解？如果不能进行解析和理解，那么规范中是否给出了足够信息来解析和理解所使用的形式化语言？若不能，读者将不能判断符号代表何意。而且，适合机器分析的形式化语言通常不容易被人类识别，并可能造成句子过长。因此，语句符号不能取代清晰的协议描述。
互联网编号分配组织(IANA)是互联网协议规定参数惟一值的权威组织。作者须与IANA规定程序保持一致来管理协议编号空间，例如IP协议的Protocol number、TCP端口号等。该过程需在向互联网标准提交草案之前完成。关于参数分配方法和当前所分配的号码，可以参见STD 2, RFC 1700 (“Assigned Numbers”)，而最新的内容已经改由IANA主页（http://www.iana.org）进行维护。此外，网络管理方面应与现有IETF管理协议保持一致，MIB的定义须与现有的管理信息结构(SMI)保持一致，并在协议或附加文档中说明，确保其能够被SMICng及类似工具解析。
互联网曾由于受到地域限制而仅限使用英语。在国际化趋势的影响下，数据可在多种语言和字符集间转换。为了迎合互联网国际化的要求，标准需要遵照BCP 18/RFC 2277“IETF Policy on Character Sets and Languages”的规定。由于同样的词语往往具有多重含义，标准性的RFC应该使用术语表，通过在术语表中定义引进的新词，作者可以避免执行中产生的误解。FYI 18/RFC 1983, “Internet Users’Glossary”提供了互联网专用词汇概念，供RFC作者参考和使用，而不希望作者背离这些术语及其含义。如有特殊情况，作者应说明改动并提供理由，改动部分也需要在术语表部分列出。
>>>ASCII图表
由于RFC及其草案往往是采用ASCII码形式的文本文件，因此其中的图表也需要使用ASCII码文本来展示。
1．数据包图表
大多数链路层、网络层与传输层协议都有数据包描述，因此数据包图表对读者来说至关重要。首选的数据包图表是比特编号位于顶端，按网路字节顺序横向排列的一长串字符。
当数据包按字节对齐而不是按字对齐时（即以字节为边界的可变长字段），将数据包图表以字节宽的格式显示。作者可用不同高度的方框安置长短不一的字符，用不规则的框架安置变长的字节。
2．状态机的描述
提出协议行为的一个便捷方法为状态机描述，即协议可由命令、运行、处理得来的一系列状态描述。状态机模型定义了建立一种状态的变量和常量、促成状态转换的事件和来自这些转换的动作。通过这些模型，可以理解任何指定事件的状态转换所导致的协议动态操作。状态转换可以用图表和时间线来详细描述。状态机只作为文本的附属品，永远无法取代规范文本的详细描述。当争议产生时，协议描述永远占优先地位。
使用状态转换图时，用状态弧线连接的方框来表示每种可能的协议状态。作者应在每个弧线上标注促成转换的事件，并用括号标注转换中发生的动作。参见STD 5/RFC 1112。
因为ASCII文本是RFC的首选存储方式，所以只能用简单的图表示，表格则可以概括更复杂或更广泛的状态转换关系。
在状态转换表中，事件纵向列出，状态横向列出，表格代表了状态转换与动作。多个动作按执行的必要性由逗号隔开，状态后的字母代表说明性的脚注。破折号指代非法转换，参见STD 51/RFC 1661。
最后一种方法是时间线。时间线的两端代表交换中的机器，作者随着时间推进（向下）沿着时间线的外部列出机器的状态，在时间线的内部表示了造成状态转换的动作。
IETF互联网标准写作指南
转自中国教育网络
互联网工程任务组IETF作为一个公开的国际性大型非政府学术与工程组织，致力于互联网相关技术标准的研发和制定。它汇集了与互联网架构和互联网顺利运作相关的网络设计者、运营者、投资人和研究开发人员，其制定的标准深受互联网界的推崇。迄今为止，IETF已经制定了4700多项RFC，包含我们所熟知的TCP协议、IP协议等等，支撑起了整个互联网协议标准。
随着我国互联网相关研究水平的逐步提高，我国已经将提出具有自主知识产权的国际标准特别是IETF RFC作为国家信息领域标准化战略的重要发展方向，国内很多高校、研究机构和企业也已经将参与IETF进行标准化工作作为重要内容。
我们知道，写得好的协议规范能使执行方更好地符合协议的规范、协议测试方获得更明确的可测试陈述、协议购买方与协议用户也会对其性能有更好的了解。然而，由于我国很多研究者对IETF文化涉足不够，即便掌握了互联网最新技术及其发展趋势，提出互联网发展的新标准，也很难写出被IETF广泛认可的RFC。为此，本文专门就此问题，介绍在写作RFC及其草案的过程中，需要注意的一些要领，供相关研究者参考。
事实上，IETF为了规范RFC及草案的书写，已经专门制定了RFC2360“互联网标准写作指南”和RFC2223“RFC写作指导”，讲解了RFC的主要组成部分，并给出了使文章连贯、准确、完整、通俗易懂的要素。协议标准化的更多信息请参见BCP 9/RFC 2026，“互联网标准程序（第三版）”，协议设计的注意事项则在RFC 1958“互联网体系结构原理”中给出。
>>>ASCII图表
由于RFC及其草案往往是采用ASCII码形式的文本文件，因此其中的图表也需要使用ASCII码文本来展示。
1．数据包图表
大多数链路层、网络层与传输层协议都有数据包描述，因此数据包图表对读者来说至关重要。首选的数据包图表是比特编号位于顶端，按网路字节顺序横向排列的一长串字符。
当数据包按字节对齐而不是按字对齐时（即以字节为边界的可变长字段），将数据包图表以字节宽的格式显示。作者可用不同高度的方框安置长短不一的字符，用不规则的框架安置变长的字节。
2．状态机的描述
提出协议行为的一个便捷方法为状态机描述，即协议可由命令、运行、处理得来的一系列状态描述。状态机模型定义了建立一种状态的变量和常量、促成状态转换的事件和来自这些转换的动作。通过这些模型，可以理解任何指定事件的状态转换所导致的协议动态操作。状态转换可以用图表和时间线来详细描述。状态机只作为文本的附属品，永远无法取代规范文本的详细描述。当争议产生时，协议描述永远占优先地位。
使用状态转换图时，用状态弧线连接的方框来表示每种可能的协议状态。作者应在每个弧线上标注促成转换的事件，并用括号标注转换中发生的动作。参见STD 5/RFC 1112。
因为ASCII文本是RFC的首选存储方式，所以只能用简单的图表示，表格则可以概括更复杂或更广泛的状态转换关系。
在状态转换表中，事件纵向列出，状态横向列出，表格代表了状态转换与动作。多个动作按执行的必要性由逗号隔开，状态后的字母代表说明性的脚注。破折号指代非法转换，参见STD 51/RFC 1661。
最后一种方法是时间线。时间线的两端代表交换中的机器，作者随着时间推进（向下）沿着时间线的外部列出机器的状态，在时间线的内部表示了造成状态转换的动作，如下图所示。
安全问题至关重要
作者必须接受其详细说明的协议遭到攻击的现实。他们有义务来说明哪些攻击有可能发生，并应详细说明攻击的性质；如果无法避免在特定环境中的攻击，则要考虑限制协议在该环境中的应用。在尽可能详尽地列出所有可能出现的安全隐患之后，作者必须阐明防御办法，并讨论可用的对策或用户应用协议会产生的风险。
有关安全问题的讨论通常集中在文件的安全问题部分（如最后一节“Security Considerations”）或文件通篇与之相关的部分。后者的优点在于其确保了安全问题是协议的主要部分的地位。可能会有几个安全机制由于多种原因未能采用，例如成本高、执行困难、所给网络环境效率低等。通过列举未采用的机制，作者可以阐明协议相关工作组已对安全问题做出了必要的考虑，同时还可以让使用该协议的用户知道是否有更适合他们特殊需求而未被采用的机制。
协议中的常见问题
协议描述必须说明协议的目的、功能、服务、操作平台、环境及协议运用的注意事项，特别是详细说明该协议的目的与用途，给读者一个立足点，以更好地理解协议。
RFC的写作目的从技术方面到管理方面多种多样，因此写作标准应该划分不同读者群。如果多方读者均出现在文档中，不同读者的不同需求也应加以细分。
与此同时，RFC作者应考虑怎样阐述细节最能达到协议的目的。简明的文章优点在于通俗易懂、较少争议以及协议执行的要求一目了然；缺点在于读者不能充分理解和体会协议背后的深层含义，从而导致执行错误。详细描述的文章可以帮助读者更好地理解协议，但同时也存在缺点，如晦涩难懂、易产生歧义、对于母语非英语的IETF读者来说，存在阅读困难的问题。解决方法是将标准划分为不同部分：一部分简洁概述，另一部分加以解释说明。
一项RFC从开始以RFC草案的形式提出到最后发表，往往需要经过多次修改。保留修改记录对RFC的编辑者或作者来说是非常必要的，作者往往需要说明先前版本与最新版本的不同，包括改变的原因，如执行经验、技术改变、用户需求等。将争议的基本内容写入，有助于防止其再次发生。另外，通过规范一个标准的回应，标准作者可以减小多方讨论产生争议的概率。
协议应清楚描述异常或超出规范行为的操作。针对这一问题，有两种处理方法，分别为删除或采用错误处理机制。作者应对发送方与接受方的行为分别进行详细描述，避免二者产生误解，尤其是对于接受方的描述。
多选项的规范加大了执行的复杂性与被误解的可能性。一种可行的方法是将文档中的协议选项进行单独描述，这能保持主要协议的结构清晰。但无论怎样，文章都要讨论是否应用该选项，及应采用何种方法等。此时作者应描述选项怎样同其他协议一同应用，以及所有选项的默认条件。为了清晰起见，作者应说明何时执行、选择的效果及用户可能面临的问题。
BCP 14/RFC 2119给出了“RFC中的要求级别关键词”。作者在确定协议要求或限制潜在有害行为时，不能偏离这些定义。这些关键术语通常采用英文大写字母的方式，参见STD 3/RFC 1122/RFC 1123。
另外，形式语言表达式可被用来定义复杂的协议概念或数据类型、详细说明数据的值，使规范简单化。作者在运用形式化语言表达式前应考虑几个问题：所使用的形式化语言能否被现有机器进行解析和理解？如果不能进行解析和理解，那么规范中是否给出了足够信息来解析和理解所使用的形式化语言？若不能，读者将不能判断符号代表何意。而且，适合机器分析的形式化语言通常不容易被人类识别，并可能造成句子过长。因此，语句符号不能取代清晰的协议描述。
互联网编号分配组织(IANA)是互联网协议规定参数惟一值的权威组织。作者须与IANA规定程序保持一致来管理协议编号空间，例如IP协议的Protocol number、TCP端口号等。该过程需在向互联网标准提交草案之前完成。关于参数分配方法和当前所分配的号码，可以参见STD 2, RFC 1700 (“Assigned Numbers”)，而最新的内容已经改由IANA主页（http://www.iana.org）进行维护。此外，网络管理方面应与现有IETF管理协议保持一致，MIB的定义须与现有的管理信息结构(SMI)保持一致，并在协议或附加文档中说明，确保其能够被SMICng及类似工具解析。
互联网曾由于受到地域限制而仅限使用英语。在国际化趋势的影响下，数据可在多种语言和字符集间转换。为了迎合互联网国际化的要求，标准需要遵照BCP 18/RFC 2277“IETF Policy on Character Sets and Languages”的规定。由于同样的词语往往具有多重含义，标准性的RFC应该使用术语表，通过在术语表中定义引进的新词，作者可以避免执行中产生的误解。FYI 18/RFC 1983, “Internet Users’Glossary”提供了互联网专用词汇概念，供RFC作者参考和使用，而不希望作者背离这些术语及其含义。如有特殊情况，作者应说明改动并提供理由，改动部分也需要在术语表部分列出。
