From 6efa525972c244d5f67862603bae74604d4245d9 Mon Sep 17 00:00:00 2001 From: Mark Lee Date: Mon, 2 Jan 2017 16:55:36 -0800 Subject: [PATCH] docs(generic): add doc formatting guidelines based off of pycodestyle --- CONTRIBUTING.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f4c1f105d..0359a66e11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ contributions. They include, but are not limited to: * Constructive feedback * [Questions about usage](#questions-about-usage) * [Bug reports / technical issues](#before-opening-bug-reportstechnical-issues) -* Documentation changes +* [Documentation changes](#documentation-changes) * Feature requests * [Pull requests](#filing-pull-requests) @@ -52,6 +52,18 @@ in the issue tracker to denote fairly-well-scoped-out bugs or feature requests t can pick up and work on. If any of those labeled issues do not have enough information, please feel free to ask constructive questions. (This applies to any open issue.) +## Documentation changes + +When changing the API documentation, here are some rules to keep in mind. + +* The first line: + * should end with a period + * should be in imperative mood (e.g., "Create" instead of "Creates") + * First line should not be the function's "signature" +* The first word of the first line: + * should be properly capitalized + * should not be "This" + ## Filing Pull Requests Here are some things to keep in mind as you file pull requests to fix bugs, add new features, etc.: