Style guide
From Artisans Asylum Wiki
- 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.