Context

• As writers and authors, we use various forms of documentation to relay our thoughts and ideas, share updates, make proposals, develop strategies, etc. Are you a documentation author who is seeking wide input, but looking for ways to expedite the comment review period?
  
  

• As readers and reviewers, we post comments on various documentations as our contributions to the greater good. Are you a documentation reviewer who is looking for ideas on how to provide your input without causing turmoil for the author?

If you responded YES to either of the above, then read on.

Guiding Principles

First, some guiding principles on why we seek wide input and why we choose to do so expediently.

We strive for transparency and openness. We build and service globally via the inclusion of a diversity of thought.
While we empower ourselves to make well-informed rapid decisions for iterative continuous learning, we also seek to learn from others.

Unintentional Gaps

While reviewers and authors have positive objectives, we run into quandaries, such as:

• At times, as reviewers, while our input is encouraged, we are concerned with any potential negative impact that our comments may create or we forget to consider the impact altogether in our enthusiasm to contribute.

• At times, as authors, we are inundated with comments and unsure of expected responses and how to proceed.

Idea: Affix Intent

Here is a simple idea that we have initiated (in 2020-Sep) in a few documentation review ceremonies, for which we are seeing initial positive feedback (from both reviewers and authors).

• As a reviewer contributing a comment, externalize your input’s intent in order to avoid misunderstanding.

  • Getting into the habit of doing so at the beginning of your comment allows you to stop and consider your intent before writing.

• As an author, use the reviewer’s stated intent as an accelerant for the conversation with clarity on an expected response.

  • If the intent is missing or unclear, take the initiative to request clarification of the intent so you are better equipped to respond.

Tip: Prefix your comment with a short phrase that summarizes your intent for easy readability and rapid mutual understanding. (We have experience with doing this when we review code changes.)

Examples

No response required

• [appreciation] This summary provides a great glimpse into …

• [kudos] I like the …

• [learning] I now understand that …

• [insight] I see that …

Input for consideration

• [brainstorm] Would it be possible to …

• [consideration] <observation> … <analysis> … <input to consider>

• [idea] <observation/insight> … What do you think about …

• [encourage] I’m quite curious to see if we have …

• [offer] If I can help in any way …

• [opportunity] Others could possibly learn from …

• [strengthen for future] In future revs, would you consider providing …

• [suggestion for next time] …

Questions seeking response

• [clarification] Would you confirm that …

• [confirmation] Is it correct that …

• [curious] Did this involve updating …

• [puzzlement] <observation> … <question>

• [question] Does this include …

Request seeking response

• [request] I’d like to see …

• [differ] From my understanding, <differing opinion/observation>