Help:Contributing/styleGuide: Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
mNo edit summary |
||
| Line 1: | Line 1: | ||
== language style == | == language style == | ||
# Get straight to the point. No word padding. Good writers express their best ideas in the least amount of words | # 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 | # 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:30, 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?