Style guide: Difference between revisions
No edit summary |
(expanding on main points. not totally done yet.) |
||
| 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 | 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 | 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. | |||
Todo: add an example of a nice annotated image. | |||
4. Link to manuals | 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) | 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 to organize articles. | |||
6. Active voice over passive | 6. Active voice over passive | ||
7. Write for your audience | 7. Write for your audience | ||
Consider your primary and secondary audiences 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? | |||
8. Be clear and concise. | 8. Be clear and concise. | ||
Revision as of 00:59, 3 November 2023
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.
Todo: add an example of a nice annotated image.
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 to organize articles.
6. Active voice over passive
7. Write for your audience
Consider your primary and secondary audiences 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?
8. Be clear and concise.
