This repository has been archived by the owner on Sep 24, 2022. It is now read-only.
Update writing-tips.md #187
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adapted language from the base template on chunking procedural steps, removed the reference to usability studies (there is not sufficient credible research on this topic). Fixes templates issue #68: #68. To verify, read the new first bullet point I've added to "Writing Procedural Steps" and decide if it fixes the issue.
|
This text is good, and I'd merge this request, except for the fact that I've just moved the base template from the incubator to the templates repository, and this fix won't be copied across Would you mind re-applying to the templates repository, dev branch, once this PR has landed: #190 |
barbaricyawps
approved these changes
Mar 3, 2021
There was a problem hiding this comment.
@aidanatwork , this looks great. I made a minor, non-blocking suggestion.
| @@ -17,7 +17,7 @@ Follow these writing guidelines when developing content using the templates avai | |||
|
|
|||
| Here are some recommendations you can use when creating procedural steps: | |||
|
|
|||
| * Usability studies show that procedures should not be more than seven primary steps long. | |||
| * For procedures with numerous steps, consider "chunking" content into sub-sections of 5-10 steps. It makes the information easier to read and remember, and gives the reader a sense of accomplishment after each chunk is completed. Chunking is recommended by major companies, such as in [Microsoft's writing style guide](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions#complex-procedures), and from the Nielsen Norman Group's [research on chunking and usability](https://www.nngroup.com/articles/short-term-memory-and-web-usability/). | |||
There was a problem hiding this comment.
Suggestion (non-blocking): Rather than putting the word chunking in quotation marks, how about italics to indicate you're introducing a new term?
|
@aidanatwork I moved the repository to |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Purpose / why
Improves first bullet for Writing Procedures.
What changes were made?
Adapted language from the base template on chunking procedural steps, removed the reference to usability studies (there is not sufficient credible research on this topic). Fixes templates issue #68: #68.
Verification
To verify, read the new first bullet point I've added to "Writing Procedural Steps" and decide if it fixes the issue.
Checklist