Style guide: Difference between revisions
From Artisans Asylum Wiki
No edit summary |
Acharlwood (talk | contribs) (Added several examples to help the audience understand some of these concepts) |
||
Line 12: | Line 12: | ||
;3. Annotate images | ;3. Annotate images | ||
[[File:highlighted_image_example.jpg|thumb|250px|Step on the foot pedal (highlighted above) to open the lid]] | |||
:While images are worth a thousand words, they can be made much more accessible with some light editing. Make judicious use of arrows, boxes, or text to make your instructions crystal clear. | :While images are worth a thousand words, they can be made much more accessible with some light editing. Make judicious use of arrows, boxes, or text to make your instructions crystal clear. | ||
;4. Link to manuals | ;4. Link to manuals | ||
Line 27: | Line 28: | ||
;6. Active voice over passive | ;6. Active voice over passive | ||
: | : The active voice is simpler, more concise, and easier for the reader. | ||
: If you'd like to learn more, [https://www.youtube.com/watch?v=W1_IRU6zx9g here's a video overview] and [https://www.grammarly.com/blog/active-vs-passive-voice/ a more comprehensive article]. | |||
;7. Write for your audience | ;7. Write for your audience | ||
:Consider your primary | :Consider your primary audience when writing any content. Who will be reading this article? What knowledge will they already have, and what are concepts you will need to briefly explain? | ||
: [https://www.youtube.com/watch?v=xyH79KQET5E Here's more on writing for your audience] and why this matters. | |||
;8. Be clear | ;8. Be concise. When writing about tasks, write about the best way to do something, not every possible way to do something. Keep explanations simple, straightforward, and clear. | ||
: | : |
Revision as of 20:34, 20 January 2024
- 0. Be friendly
- Please write your articles in a friendly tone reflective of our welcoming community.
- 1. Use simple words
- No need to use big words when simples ones will do.
- 2. Define necessary jargon
- In some cases, you will need to use jargon (technical terms). If you are introducing jargon, please make sure to define it.
- 3. Annotate images
- While images are worth a thousand words, they can be made much more accessible with some light editing. Make judicious use of arrows, boxes, or text to make your instructions crystal clear.
- 4. Link to manuals
- Rather than including full instructions in this wiki, link out to manuals so that interested users may refer to them. Most readers will only be interest in basic instructions.
- 5. No walls of text (structure your content)
- Walls of text are super intimidating. Structure your content by splitting text into shorter paragraphs and make use of headings or other formatting (e.g. lists) to organize articles.
- 6. Active voice over passive
- The active voice is simpler, more concise, and easier for the reader.
- If you'd like to learn more, here's a video overview and a more comprehensive article.
- 7. Write for your audience
- Consider your primary audience when writing any content. Who will be reading this article? What knowledge will they already have, and what are concepts you will need to briefly explain?
- Here's more on writing for your audience and why this matters.
- 8. Be concise. When writing about tasks, write about the best way to do something, not every possible way to do something. Keep explanations simple, straightforward, and clear.