From 97059a651e21eb626345023bf916418a4fcd081e Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Mon, 25 Nov 2024 17:25:26 +0000 Subject: [PATCH 1/7] Move commenting-guide from glossary to tactics --- src/content/tactic/commenting-guide.adoc | 129 +++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 src/content/tactic/commenting-guide.adoc diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc new file mode 100644 index 0000000..b8bf4e5 --- /dev/null +++ b/src/content/tactic/commenting-guide.adoc @@ -0,0 +1,129 @@ += Commenting guide for collaborative document reviews + +_Tips for applying comments and track-changes during collaborative document reviews, when using tools like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab._ + +*Version:* 1.1 +*Date:* July 2024 + +== Scope +Tips in this guide are considered recommendations, to be applied most of the time, rather than being hard rules. + +== Tips for reviewers + +=== Comments instead of track-changes +Use comments instead of track changes. + + - Documents become messy and difficult to understand when multiple reviewers apply track changes on top of each other. + - A later reviewer should be able to easily understand the author’s original intent. + +==== Possible exceptions + - Trivial changes, such as punctuation tweaks. + - Adding all the text for a new section. + - If there is only one reviewer. + +=== Highlight one word instead of a slab of text +Select a word or a few words instead of a sentence or a slab of text to comment on. + + - This ensures space is left for other reviewers to attach a separate comment. + +=== One comment thread per idea +Don’t put multiple ideas into one comment. + + - This allows a thread to develop around one idea, and for each idea to be closed separately. + +=== Add to comments + - You can expand on, or disagree with, a prior reviewer’s idea by replying to their comment. + - You can support a comment by simply replying with a “+1”. + +=== Adopt commenting conventions +Adopt a commenting convention, such as https://conventionalcomments.org/. + + - This helps with consistency and conveying the importance of each comment. + +Commonly used https://conventionalcomments.org/ labels include: + + - *suggestion:* Propose improvements to the current subject. + - *nitpick:* Trivial preference-based request. + - *praise:* Highlight something positive. + - *question:* You have a potential concern but are not sure if it's relevant. + - *thought:* An idea that popped up while reviewing. + +Sometimes add a decoration: + + - *(blocking):* Should block acceptance until resolved. + +Example: + + - _"*suggestion (blocking):* This sentence is ambiguous. Suggest reword as {…}"_ + +=== Reference best-practices +If your comment recommends applying a principle from a guide or best practice, provide a hyper-link to the relevant section in the guide. + + - This helps the author learn about best practices. + - Referencing best practices provides justification and authority to support your reasoning. + +Typically only provide one reference to a best practice, in the first applicable comment. + +==== Possible exceptions + - As a reviewer, you may be time-constrained. Finding references is time-consuming. + - You may know that the author is already familiar with the relevant section of the guide. + +=== Login before commenting +Preferably login to your Google or Microsoft account before commenting on a doc. + + - Comments are attributed to you rather than “Anonymous”, and adds a personal touch to your community. + - You will receive email updates when an author responds to, or resolves, your comment. + +== Tips for authors + +=== Set a review timeframe +An author should specify a timeframe for feedback when asking for a review. + + - This helps stakeholders plan their time. + +=== Select appropriate reviewers and scope + - Typically, different reviewers would be asked to consider different review criteria based on their skillset. + - Ensure the depth of review requested aligns with the document importance. + +An author should describe scope and criteria when asking for a review. Criteria may include: + + - Technical accuracy. + - Clarity and related writing principles. + - Alignment with a template. + - Alignment with a style guide. + +=== Designated authority to accept/reject changes +A designated person makes the final decision to accept or reject all non-trivial comments. + + - Typically, this is the document author, but may be a senior reviewer or subject matter expert. + - Successful incorporation of advice is a key indicator of quality documentation. + +=== Reasoned reply to each comment +An author should reply to each non-trivial comment before closing. Typically note your action and reasoning. Feel free to add a personal touch to your message. + +Examples: + + - "Agree, done." + - "Thanks for the suggestion, done." + - "Not done, {short reason}." + +Why reply: + + - Replying is a courtesy to the reviewer. + - It helps the reviewer understand the reasoning behind the decision. + - Sometimes it provides a learning opportunity for the reviewer. + - It provides an opportunity for a reviewer to clarify a misunderstood comment. + +In Google Docs and Word this feedback is automatically emailed to the commenter. + +=== Resolve completed comments +Once actioned, an author should select a comment thread’s “Resolved” button to hide the comment thread. + + - This helps the author and readers see what’s left to be actioned. + +=== Use version history - name releases +Label each document version you put out for review (if your tool supports it). + + - This enables reviewers to compare changes between reviews, which reduces their review overhead. + +In Google Docs, this is supported under File -> Version History. (It requires reviewers to have Edit Access to the doc, which enables viewers to see Version History.) \ No newline at end of file -- GitLab From 6a8a4899e764c88d0c6dd004dc3d9e12a8964d21 Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Mon, 25 Nov 2024 17:44:41 +0000 Subject: [PATCH 2/7] Add frontmatter to commenting-guide, e --- src/content/tactic/commenting-guide.adoc | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc index b8bf4e5..d230bb4 100644 --- a/src/content/tactic/commenting-guide.adoc +++ b/src/content/tactic/commenting-guide.adoc @@ -1,8 +1,19 @@ -= Commenting guide for collaborative document reviews +--- +title: Commenting guide for collaborative document reviews +summary: Tips for applying comments and track-changes during collaborative document reviews, when using tools like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab. +image: ia-guide/stuck.png +author: + - Cameron Shorter +tags: + - reviewing +layout: blocks +blocks: + - block_ref: content + title: Commenting guide for collaborative document reviews +--- + +*Version:* 1.1 -_Tips for applying comments and track-changes during collaborative document reviews, when using tools like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab._ - -*Version:* 1.1 *Date:* July 2024 == Scope -- GitLab From 4fa5420cc4f2c4e62a46fca1cb5bd6a0cf15733f Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Thu, 28 Nov 2024 11:07:55 +0000 Subject: [PATCH 3/7] Add Reviewer.jpg image --- src/content/tactic/commenting-guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc index d230bb4..bdbc93d 100644 --- a/src/content/tactic/commenting-guide.adoc +++ b/src/content/tactic/commenting-guide.adoc @@ -1,7 +1,7 @@ --- title: Commenting guide for collaborative document reviews summary: Tips for applying comments and track-changes during collaborative document reviews, when using tools like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab. -image: ia-guide/stuck.png +image: Reviewer.jpeg author: - Cameron Shorter tags: -- GitLab From 80a3a9cee1c5da999075190dbb4faad185a587e0 Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Thu, 28 Nov 2024 11:38:26 +0000 Subject: [PATCH 4/7] Changed author tag in commenting-guide --- src/content/tactic/commenting-guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc index bdbc93d..8866c86 100644 --- a/src/content/tactic/commenting-guide.adoc +++ b/src/content/tactic/commenting-guide.adoc @@ -3,7 +3,7 @@ title: Commenting guide for collaborative document reviews summary: Tips for applying comments and track-changes during collaborative document reviews, when using tools like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab. image: Reviewer.jpeg author: - - Cameron Shorter + - cameron_shorter tags: - reviewing layout: blocks -- GitLab From 65e44cbb404cf14a2edf5a0968612a017f4ad9b9 Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Thu, 28 Nov 2024 20:07:50 +0000 Subject: [PATCH 5/7] escape curly brackets in commenting-guide --- src/content/tactic/commenting-guide.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc index 8866c86..4dbe624 100644 --- a/src/content/tactic/commenting-guide.adoc +++ b/src/content/tactic/commenting-guide.adoc @@ -65,7 +65,7 @@ Sometimes add a decoration: Example: - - _"*suggestion (blocking):* This sentence is ambiguous. Suggest reword as {…}"_ + - _"*suggestion (blocking):* This sentence is ambiguous. Suggest reword as \{…\}"_ === Reference best-practices If your comment recommends applying a principle from a guide or best practice, provide a hyper-link to the relevant section in the guide. @@ -116,7 +116,7 @@ Examples: - "Agree, done." - "Thanks for the suggestion, done." - - "Not done, {short reason}." + - "Not done, \{short reason\}." Why reply: -- GitLab From 51e6019b07bd09173401bd04bd97d71458516eb4 Mon Sep 17 00:00:00 2001 From: Cameron Shorter Date: Thu, 28 Nov 2024 20:29:02 +0000 Subject: [PATCH 6/7] Remove curly brackets in commenting-guide --- src/content/tactic/commenting-guide.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc index 4dbe624..5960d86 100644 --- a/src/content/tactic/commenting-guide.adoc +++ b/src/content/tactic/commenting-guide.adoc @@ -65,7 +65,7 @@ Sometimes add a decoration: Example: - - _"*suggestion (blocking):* This sentence is ambiguous. Suggest reword as \{…\}"_ + - _"*suggestion (blocking):* This sentence is ambiguous. Suggest reword as …"_ === Reference best-practices If your comment recommends applying a principle from a guide or best practice, provide a hyper-link to the relevant section in the guide. @@ -116,7 +116,7 @@ Examples: - "Agree, done." - "Thanks for the suggestion, done." - - "Not done, \{short reason\}." + - "Not done, short reason." Why reply: -- GitLab From e4153727c599324561ea6b570c79fac8ad555ec5 Mon Sep 17 00:00:00 2001 From: "Bryan Klein (TECi)" Date: Thu, 12 Dec 2024 00:29:22 +0000 Subject: [PATCH 7/7] Formatting for AsciiDoc and Tactic Data --- src/content/tactic/commenting-guide.adoc | 129 +++++++++++++---------- 1 file changed, 74 insertions(+), 55 deletions(-) diff --git a/src/content/tactic/commenting-guide.adoc b/src/content/tactic/commenting-guide.adoc index 5960d86..0a16762 100644 --- a/src/content/tactic/commenting-guide.adoc +++ b/src/content/tactic/commenting-guide.adoc @@ -3,138 +3,157 @@ title: Commenting guide for collaborative document reviews summary: Tips for applying comments and track-changes during collaborative document reviews, when using tools like Google Docs, Word, LibreOffice and Pages. Many tips also apply to docs-as-code reviews in tools like GitHub and GitLab. image: Reviewer.jpeg author: - - cameron_shorter +- cameron_shorter tags: - - reviewing +- reviewing layout: blocks blocks: - - block_ref: content +- block_ref: content title: Commenting guide for collaborative document reviews +version: 1.1 +date: 2024-07 --- -*Version:* 1.1 - -*Date:* July 2024 - == Scope + Tips in this guide are considered recommendations, to be applied most of the time, rather than being hard rules. == Tips for reviewers === Comments instead of track-changes + Use comments instead of track changes. - - Documents become messy and difficult to understand when multiple reviewers apply track changes on top of each other. - - A later reviewer should be able to easily understand the author’s original intent. +- Documents become messy and difficult to understand when multiple reviewers apply track changes on top of each other. +- A later reviewer should be able to easily understand the author's original intent. ==== Possible exceptions - - Trivial changes, such as punctuation tweaks. - - Adding all the text for a new section. - - If there is only one reviewer. + +- Trivial changes, such as punctuation tweaks. +- Adding all the text for a new section. +- If there is only one reviewer. === Highlight one word instead of a slab of text + Select a word or a few words instead of a sentence or a slab of text to comment on. - - This ensures space is left for other reviewers to attach a separate comment. +- This ensures space is left for other reviewers to attach a separate comment. === One comment thread per idea -Don’t put multiple ideas into one comment. - - This allows a thread to develop around one idea, and for each idea to be closed separately. +Don't put multiple ideas into one comment. + +- This allows a thread to develop around one idea, and for each idea to be closed separately. === Add to comments - - You can expand on, or disagree with, a prior reviewer’s idea by replying to their comment. - - You can support a comment by simply replying with a “+1”. + +- You can expand on, or disagree with, a prior reviewer's idea by replying to their comment. +- You can support a comment by simply replying with a "+1". === Adopt commenting conventions + Adopt a commenting convention, such as https://conventionalcomments.org/. - - This helps with consistency and conveying the importance of each comment. +- This helps with consistency and conveying the importance of each comment. Commonly used https://conventionalcomments.org/ labels include: - - *suggestion:* Propose improvements to the current subject. - - *nitpick:* Trivial preference-based request. - - *praise:* Highlight something positive. - - *question:* You have a potential concern but are not sure if it's relevant. - - *thought:* An idea that popped up while reviewing. +suggestion:: Propose improvements to the current subject. +nitpick:: Trivial preference-based request. +praise:: Highlight something positive. +question:: You have a potential concern but are not sure if it's relevant. +thought:: An idea that popped up while reviewing. Sometimes add a decoration: - - *(blocking):* Should block acceptance until resolved. +__label__ (blocking):: Should block acceptance until resolved. Example: - - _"*suggestion (blocking):* This sentence is ambiguous. Suggest reword as …"_ +__"suggestion (blocking): This sentence is ambiguous. Suggest reword as …"__ === Reference best-practices + If your comment recommends applying a principle from a guide or best practice, provide a hyper-link to the relevant section in the guide. - - This helps the author learn about best practices. - - Referencing best practices provides justification and authority to support your reasoning. +- This helps the author learn about best practices. +- Referencing best practices provides justification and authority to support your reasoning. Typically only provide one reference to a best practice, in the first applicable comment. ==== Possible exceptions - - As a reviewer, you may be time-constrained. Finding references is time-consuming. - - You may know that the author is already familiar with the relevant section of the guide. + +- As a reviewer, you may be time-constrained. +Finding references is time-consuming. +- You may know that the author is already familiar with the relevant section of the guide. === Login before commenting -Preferably login to your Google or Microsoft account before commenting on a doc. - - Comments are attributed to you rather than “Anonymous”, and adds a personal touch to your community. - - You will receive email updates when an author responds to, or resolves, your comment. +Preferably login to your account before commenting on a doc. + +- Comments are attributed to you rather than "Anonymous", and adds a personal touch to your community. +- You will receive email updates when an author responds to, or resolves, your comment. == Tips for authors === Set a review timeframe + An author should specify a timeframe for feedback when asking for a review. - - This helps stakeholders plan their time. +- This helps stakeholders plan their time. === Select appropriate reviewers and scope - - Typically, different reviewers would be asked to consider different review criteria based on their skillset. - - Ensure the depth of review requested aligns with the document importance. -An author should describe scope and criteria when asking for a review. Criteria may include: +- Typically, different reviewers would be asked to consider different review criteria based on their skillset. +- Ensure the depth of review requested aligns with the document importance. + +An author should describe scope and criteria when asking for a review. +Criteria may include: - - Technical accuracy. - - Clarity and related writing principles. - - Alignment with a template. - - Alignment with a style guide. +- Technical accuracy. +- Clarity and related writing principles. +- Alignment with a template. +- Alignment with a style guide. === Designated authority to accept/reject changes + A designated person makes the final decision to accept or reject all non-trivial comments. - - Typically, this is the document author, but may be a senior reviewer or subject matter expert. - - Successful incorporation of advice is a key indicator of quality documentation. +- Typically, this is the document author, but may be a senior reviewer or subject matter expert. +- Successful incorporation of advice is a key indicator of quality documentation. === Reasoned reply to each comment -An author should reply to each non-trivial comment before closing. Typically note your action and reasoning. Feel free to add a personal touch to your message. + +An author should reply to each non-trivial comment before closing. +Typically note your action and reasoning. +Feel free to add a personal touch to your message. Examples: - - "Agree, done." - - "Thanks for the suggestion, done." - - "Not done, short reason." +- "Agree, done." +- "Thanks for the suggestion, done." +- "Not done, short reason." Why reply: - - Replying is a courtesy to the reviewer. - - It helps the reviewer understand the reasoning behind the decision. - - Sometimes it provides a learning opportunity for the reviewer. - - It provides an opportunity for a reviewer to clarify a misunderstood comment. +- Replying is a courtesy to the reviewer. +- It helps the reviewer understand the reasoning behind the decision. +- Sometimes it provides a learning opportunity for the reviewer. +- It provides an opportunity for a reviewer to clarify a misunderstood comment. -In Google Docs and Word this feedback is automatically emailed to the commenter. +NOTE: In Google Docs and Word this feedback is automatically emailed to the commenter. === Resolve completed comments -Once actioned, an author should select a comment thread’s “Resolved” button to hide the comment thread. - - This helps the author and readers see what’s left to be actioned. +Once actioned, an author should select a comment thread's "Resolved" button to hide the comment thread. + +- This helps the author and readers see what's left to be actioned. === Use version history - name releases + Label each document version you put out for review (if your tool supports it). - - This enables reviewers to compare changes between reviews, which reduces their review overhead. +- This enables reviewers to compare changes between reviews, which reduces their review overhead. -In Google Docs, this is supported under File -> Version History. (It requires reviewers to have Edit Access to the doc, which enables viewers to see Version History.) \ No newline at end of file +NOTE: In Google Docs, this is supported under File -> Version History. +(It requires reviewers to have Edit Access to the doc, which enables viewers to see Version History.) -- GitLab