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

This commit is contained in:
Ana Martins 2023-11-07 22:37:26 +00:00 committed by Colin Jarvis
parent 198115b0c4
commit a0699d4353

View File

@ -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, …”