Help:Contributing/styleGuide: Difference between revisions
Jump to navigation
Jump to search
mNo edit summary |
mNo edit summary |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 7: | Line 7: | ||
== Presentation == | == Presentation == | ||
# Show, don't tell. Rather than writing at length about what a config does, show | # Show, don't tell. Rather than writing at length about what a config does, show a real-world code example with 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? | ||
| Line 15: | Line 15: | ||
Some good examples | Some good examples | ||
[[Cheatsheets:SPARQL|Technical documentation example]] | [[Cheatsheets:SPARQL|Technical documentation example: cheatsheet]] | ||
[[Cheatsheets:Markdown|Technical documentation example: cheatsheet 2]] | |||
Latest revision as of 18:16, 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 a real-world code example with 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