From 1aa805dddcd2038eefe074890594bc4ba451d1fc Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Wed, 23 Jan 2019 13:18:15 -0800 Subject: [PATCH] Minor revisions to structure-formatting and writing-guide (based on feedback) Signed-off-by: Kristal Dale --- .../collaboration/structure-formatting.rst | 9 ++++----- .../reference/collaboration/writing-guide.rst | 15 +++------------ 2 files changed, 7 insertions(+), 17 deletions(-) diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst index 811ee4dd..6391dccb 100644 --- a/source/clear-linux/reference/collaboration/structure-formatting.rst +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -25,8 +25,8 @@ websites: * `Sphinx documentation`_ * `reStructuredText Primer`_ -You can view the content directly in the .rst markup files, or you can generate -the HTML content by installing and running the documentation locally. To run the +You can view the content directly in the .rst markup files, or generate the HTML +content by installing and building the documentation locally. To run the documentation locally, follow the instructions found in the `documentation repository`_ README. @@ -241,9 +241,8 @@ Remove trailing whitespace from your documents. Code blocks and examples ************************ -When providing example code or commands that are less than 10 lines, use the -`Sphinx code-block directive`_. Use the appropriate syntax highlighting for the -example command or code. +When providing example code or commands use the `Sphinx code-block directive`_. +Select the appropriate syntax highlighting for the example command or code. For example, if showing console output, use console highlighting: diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst index 8f307b2a..f69a0344 100644 --- a/source/clear-linux/reference/collaboration/writing-guide.rst +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -32,8 +32,9 @@ Introduction, body, and conclusion. Be friendly =========== -We write for our peers and want to be familiar. Use the second person, you or -we. Be professional, respectful, and cooperative. +We write for our peers and want to be familiar. Take a personal tone as if you +were speaking directly to the reader. Use "you" to address the reader and "we" +to refer to our view. Be professional, respectful, and cooperative. Assume your audience has the same level of technical understanding and expertise as you did when you first started collaborating. Do not talk down to our @@ -289,16 +290,6 @@ to two. For example: Power management mechanism integration policies. -Or: - -**Use this:** :: - - Requirements for test desks that measure signal integrity. - -**Not this:** :: - - Signal integrity test deck requirements. - .. _parallelism: Parallelism