Style guide: Difference between revisions
From Artisans Asylum Wiki
No edit summary |
Acharlwood (talk | contribs) mNo edit summary |
||
(10 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
;0. Be friendly | |||
:Please write your articles in a friendly tone reflective of our welcoming community. | |||
1. Use simple words | ;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 | |||
[[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, text, or highlights to make your instructions crystal clear. | |||
8. Keep | |||
;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, [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 | |||
: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 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. | |||
[[Category:A2 Wiki Help]] |
Latest revision as of 13:28, 9 February 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, text, or highlights 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.