Difference between revisions of "Wiki.emacinc.com:Style Guide"
m (minor changes) |
(view and audience) |
||
| Line 4: | Line 4: | ||
While not completely formal, this wiki is a collection of professional technical documents and should be written as such. Advertising rhetoric, colloquialism, and informal tones should be avoided. Several important points are discussed below. | While not completely formal, this wiki is a collection of professional technical documents and should be written as such. Advertising rhetoric, colloquialism, and informal tones should be avoided. Several important points are discussed below. | ||
| − | === | + | === View === |
| − | For the most part, writing should be | + | For the most part, writing on this wiki should be done from the third or second person point of view. However, writing in the first person is not necessarily wrong. Contrary to rules which prohibit first person in all formal technical writing, use of "we" can be effective in certain cases, particularly in some more complicated step-by-step procedures where it can help to include the reader in the process. At the same time, use of "I" should generally be avoided on this project. Simply examine use of first person carefully to ensure that it does not impact the overall effectiveness or readability of the article. Some general points to consider: |
| + | # Avoid use of first person when it relegates use of first person throughout the entire article. | ||
| + | # Avoid use of first person when it sets an informal or unprofessional tone in the article. | ||
| + | # Use first person when it improves flow and effectiveness, for example by connecting the reader to the subject. | ||
| + | === Audience === | ||
| + | The audience of this wiki will have a varying degree of knowledge and experience with the topics covered. Readers will generally be customers of EMAC products and their needs should be taken into consideration when creating articles. It should be assumed that the readers have some software and hardware development experience, but may have limited knowledge of Linux, or embedded Linux in particular. Some things to take into account related to audience are: | ||
| + | # The organization of the wiki and topic separation should be set up so that it is easy for readers to find the information that they need while skipping the information that they already know (for example, "What is Linux?" versus a specific procedure on how to access GPIOs using the EMAC interface). | ||
| + | |||
| + | |||
| + | |||
| + | == Review == | ||
== Organization == | == Organization == | ||
Revision as of 10:40, 25 November 2013
This page serves as a set of guidelines for style, formatting, and content across the EMAC Wiki project. While there will be exceptions, following the standards set here will promote consistency and best-practices across the wiki and provide a reference for content review. This guide should be treated as a living document and updated with the current conventions.
Contents
Writing Style
While not completely formal, this wiki is a collection of professional technical documents and should be written as such. Advertising rhetoric, colloquialism, and informal tones should be avoided. Several important points are discussed below.
View
For the most part, writing on this wiki should be done from the third or second person point of view. However, writing in the first person is not necessarily wrong. Contrary to rules which prohibit first person in all formal technical writing, use of "we" can be effective in certain cases, particularly in some more complicated step-by-step procedures where it can help to include the reader in the process. At the same time, use of "I" should generally be avoided on this project. Simply examine use of first person carefully to ensure that it does not impact the overall effectiveness or readability of the article. Some general points to consider:
- Avoid use of first person when it relegates use of first person throughout the entire article.
- Avoid use of first person when it sets an informal or unprofessional tone in the article.
- Use first person when it improves flow and effectiveness, for example by connecting the reader to the subject.
Audience
The audience of this wiki will have a varying degree of knowledge and experience with the topics covered. Readers will generally be customers of EMAC products and their needs should be taken into consideration when creating articles. It should be assumed that the readers have some software and hardware development experience, but may have limited knowledge of Linux, or embedded Linux in particular. Some things to take into account related to audience are:
- The organization of the wiki and topic separation should be set up so that it is easy for readers to find the information that they need while skipping the information that they already know (for example, "What is Linux?" versus a specific procedure on how to access GPIOs using the EMAC interface).
