Help:Contributing/styleGuide: Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
|||
| Line 1: | Line 1: | ||
== | == 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. | ||
| Line 5: | Line 5: | ||
# 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 == | ||
# 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. | ||
| Line 11: | Line 11: | ||
# 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? | ||
== | == Turn advice into action == | ||
Some good examples | Some good examples | ||
[[Cheatsheets:SPARQL|Technical documentation example]] | [[Cheatsheets:SPARQL|Technical documentation example]] | ||
Revision as of 12:41, 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?
Turn advice into action
Some good examples