Fixed what looks like a markdown formatting issue. (#826)

pull/827/head
Ana Martins 6 months ago committed by GitHub
parent 7065abc046
commit 8effa95a96
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -36,7 +36,7 @@ Badly written text is taxing to read. Minimize the tax on readers by writing wel
**Avoid demonstrative pronouns (e.g., “this”), especially across sentences.** For example, instead of saying “Building on our discussion of the previous topic, now lets discuss function calling” try “Building on message formatting, now lets discuss function calling.” The second sentence is easier to understand because it doesnt burden the reader with recalling the previous topic. Look for opportunities to cut demonstrative pronouns altogether: e.g., “Now lets discuss function calling.”
**\*Be consistent.** Human brains are amazing pattern matchers.\* Inconsistencies will annoy or distract readers. If we use Title Case everywhere, use Title Case. If we use terminal commas everywhere, use terminal commas. If all of the Cookbook notebooks are named with underscores and sentence case, use underscores and sentence case. Dont do anything that will cause a reader to go huh, thats weird. Help them focus on the content, not its inconsistencies.
**Be consistent.** Human brains are amazing pattern matchers. Inconsistencies will annoy or distract readers. If we use Title Case everywhere, use Title Case. If we use terminal commas everywhere, use terminal commas. If all of the Cookbook notebooks are named with underscores and sentence case, use underscores and sentence case. Dont do anything that will cause a reader to go huh, thats weird. Help them focus on the content, not its inconsistencies.
**Dont tell readers what they think or what to do.** Avoid sentences like “Now you probably want to understand how to call a function” or “Next, youll need to learn to call a function.” Both examples presume a readers state of mind, which may annoy them or burn our credibility. Use phrases that avoid presuming the readers state. E.g., “To call a function, …”

Loading…
Cancel
Save