Help:Contributing/styleGuide: Difference between revisions
Jump to navigation
Jump to search
1st draft |
mNo edit summary |
||
| Line 1: | Line 1: | ||
== language style == | == language style == | ||
# Get straight to the point. No word padding. | # Get straight to the point. No word padding. Good writers express their best ideas in the least amount of words; | ||
# | # Long sentences with complex structures are hard to read. Prefer a few shorter sentences than one long one with multiple sub-clauses; | ||
# Use proper vocabulary. Do not use complex words to show off, but also do not oversimplify risking ambiguity | # Use proper vocabulary. Do not use complex words to show off, but also do not oversimplify risking ambiguity. | ||
== presentation == | == presentation == | ||
# Show, don't tell. Rather than writing at length about what a config does, show in a sandbox example the results | # Show, don't tell. Rather than writing at length about what a config does, show in a sandbox example the results; | ||
# Use tables for comparison | # Use tables for comparison; | ||
# Keep your reader in mind: What is their expected level of expertise? What's their goal? What content would engage them? | # Keep your reader in mind: What is their expected level of expertise? What's their goal? What content would engage them? | ||
Revision as of 07:29, 19 August 2026
language style
- Get straight to the point. No word padding. Good writers express their best ideas in the least amount of words;
- Long sentences with complex structures are hard to read. Prefer a few shorter sentences than one long one with multiple sub-clauses;
- Use proper vocabulary. Do not use complex words to show off, but also do not oversimplify risking ambiguity.
presentation
- Show, don't tell. Rather than writing at length about what a config does, show in a sandbox example the results;
- Use tables for comparison;
- Keep your reader in mind: What is their expected level of expertise? What's their goal? What content would engage them?