Style guide: Difference between revisions

From Artisans Asylum Wiki
(expanding on main points. not totally done yet.)
mNo edit summary
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
0. Be friendly
;0. Be friendly


Please write your articles in a friendly tone reflective of our welcoming community.
: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.
: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.
: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.
[[File:highlighted_image_example.jpg|thumb|250px|Step on the foot pedal (highlighted above) to open the lid]]


Todo: add an example of a nice annotated image.
: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.
;4. Link to manuals


5. No walls of text (structure your content)
: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.


Walls of text are super intimidating. Structure your content by splitting text into shorter paragraphs and make use of headings to organize articles.
;5. No walls of text (structure your content)


6. Active voice over passive
: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.


7. Write for your audience
: 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].


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?
;7. Write for your audience


8. Be clear and concise.
: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
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.


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.