Skip to content

Commit

Permalink
Fixed what looks like a markdown formatting issue. (#826)
Browse files Browse the repository at this point in the history
  • Loading branch information
OutSystemsAMM authored Nov 7, 2023
1 parent 7065abc commit 8effa95
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion articles/what_makes_documentation_good.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 let’s discuss function calling” try “Building on message formatting, now let’s discuss function calling.” The second sentence is easier to understand because it doesn’t burden the reader with recalling the previous topic. Look for opportunities to cut demonstrative pronouns altogether: e.g., “Now let’s 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. Don’t do anything that will cause a reader to go ‘huh, that’s 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. Don’t do anything that will cause a reader to go ‘huh, that’s weird.’ Help them focus on the content, not its inconsistencies.

**Don’t 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, you’ll need to learn to call a function.” Both examples presume a reader’s state of mind, which may annoy them or burn our credibility. Use phrases that avoid presuming the reader’s state. E.g., “To call a function, …”

Expand Down

0 comments on commit 8effa95

Please sign in to comment.