From b648c162baaa039392893dfced4b9198f70225bc Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Fri, 9 Jun 2023 09:46:42 -0700 Subject: [PATCH] feat(AIP-8): add voice guidance Clear guidance around the voice of AIPs will ensure consistent style. --- aip/general/0008.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/aip/general/0008.md b/aip/general/0008.md index 8d62fe6a3b..0617ee5916 100644 --- a/aip/general/0008.md +++ b/aip/general/0008.md @@ -28,6 +28,20 @@ While the length of AIPs will necessarily vary based on the complexity of the question, most AIPs **should** be able to cover their content in roughly two printed pages. +## Voice + +AIPs have a consistent voice to ensure clear, readable and succinct guidance. + +- AIPs **must** not include ambiguous or unclear phrasing. +- AIPs **must** use active voice where possible. +- AIPs **must** not use [pleonastic][] words or phrases. + +AIPs **should** format guidance in a bulleted list of statements. Exceptions +include: + +- Where guidance does not fit succinctly in a bulleted list. +- Where elaboration is necessary such that a paragraph is more suitable. + ### File structure AIPs **must** be written in Markdown, and **must** be named using their @@ -194,6 +208,7 @@ branch. [aip-1]: ./0001.md [protocol buffers]: https://developers.google.com/protocol-buffers/ [rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt +[pleonastic]: https://en.wikipedia.org/wiki/Pleonasm ## Changelog