EOWG: Tips for effective comments [important]

Hi all,

As mentioned in the call today, it is helpful if we provide specific, clear, succinct comments that are quickly understandable to all EOWG participants and easily action-able by the editors. This is especially important when we are in the stage of polishing up wording or coding to get a document done.

Here is a format that we've found useful in the past:
* priority: [mild/medium/strong]
* location: (e.g., # link to section)
* current wording/code:
* suggested revision:
* rationale:

A shortcut that is usually best for the commenter and the editor is to use GitHub to:
1. Fork and make the suggested change (that takes care location, current wording, suggested revision)
2. In the comment area,
* Put a short description of the location &/or change (e.g., "introduction copyedits") in the box replacing "Update index.html.erb.md" or whatever it says
* Put the *priority* and *rationale* in the box replacing "Add an optional extended description..."
3. Submit pull request

(fyi: You can edit these afterwards if you need to make clarification; however, be aware if there are comments after yours that might mess up the logic and flow of the thread.)

This helps EOWG process all our input more efficiently.

Thanks!
~Shawn

Received on Friday, 2 October 2015 15:44:09 UTC