This guide provides guidance for content on the IETF Website and other collateral materials. The goal is to ensure content is relevant, accessible, and coherent. This guide is also intended to promote consistency across and with other IETF-related materials, including the RFC series. This document does not aim to be comprehensive or static; it's a living document that will evolve.
This guide should be considered in the broader context and purposes of IETF communications, which aim to:
- help individuals who are already actively participating in the IETF "get the work of the IETF done",
- encourage individuals who could participate in and contribute to the IETF to become active contributors, and
- provide non-participants looking to find out more about the IETF a better understanding of the IETF's role as the Internet's premier standards organization.
Suggestions are welcome! Please send them to: support@ietf.org
The general approach to writing style for IETF materials is to follow the lead of the RFC Editor’s approach, to the extent that this serves the purposes of IETF communications efforts.
For example, the Chicago Manual of Style provides a general approach on matters of writing style. However, for issues related to citation and other topics that arise in the context of the RFC series, it is preferable to follow the RFC Editor style guide, when that does not contradict the more general purposes of IETF communications (e.g. being understandable to non-IETF participants). The RFC Editor also provides some particular guidance for Web-based materials and on abbreviations and whether they need to be expanded, though for the www.ietf.org it is akwats better to err on the side of expanding acronyms if there is a question about whether or not a term will be familiar to the reader.
IETF participants and potential participants are from all over the world and many are not native English speakers. Thus, it is important to ensure content is easy to read. In particular, writing should not rely on idioms that may be difficult for non-native speakers to understand. The online Hemingway app can be helpful in assessing readability. It rates this paragraph at a grade 7 level. Aim for writing rated no higher than grade 10.
Links should be embedded in text that explains the content to which they point. Raw URLs in the text of a webpage, or links embedded in generic text like “click here” are hard to read and unfriendly to screen readers, which makes content less accessible. Links should be concise, descriptive, and meaningful out of context. For more detail, see these guidelines on hyperlinks in web pages.
When linking to group charters, Internet-Drafts (I-D), or other IETF working documents or products, the IETF Datatracker is the preferred resource. For links to RFCs, the RFC Editor website should be used.