Difference between revisions of "Wiki.emacinc.com:Style Guide"
(view and audience) |
(more content) |
||
| Line 1: | Line 1: | ||
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. | 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. | ||
| − | == Writing | + | == Writing Guidelines == |
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. | ||
| Line 14: | Line 14: | ||
# 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). | # 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). | ||
| + | === Content === | ||
| + | Article content should be restricted to fall within the scope of the page. This helps reduce overlap between pages and makes it easier for the reader to find the information that they are searching for. Keep in mind that shorter articles are more likely to be read. The wiki should focus on content specific to EMAC products and software. While it is important to provide background information and other instructions in-line with the article at times, it is often appropriate to refer to outside documentation such as man pages for this information, particularly when it can be assumed that most of the audience will already be familiar with the information. | ||
| + | ==== Linking Other Documetation ==== | ||
| + | When linking to other sites and documentation, it is important to use reliable sites with URLs that are relatively stable. For example, https://www.kernel.org/doc/man-pages/ for man pages. This helps reduces maintenance and ensures that the content on the pages that we link to is professional. | ||
| + | |||
| + | === Style and Standards === | ||
| + | Writing on this wiki should be clear, detailed, and concise; following standards of technical writing. This does not mean that the writing needs to be completely formal or dry, but it should be professional. The points below should be used as guidelines when writing and reviewing: | ||
| + | * Avoid wordiness and repetitive language. | ||
| + | * Use simple sentences where possible with smooth transitions between sentences and topics. | ||
| + | * Use the best word(s) to describe what you want to convey to the reader. Think, "Is there an easier way to say this?" This is challenging because much of the information is highly technical. Keep in mind that some of the audience may not be native English speakers. | ||
| + | * Avoid colloquialism and cliches. | ||
| + | * Be detailed and precise about the topic at hand, and leave out unnecessary details. | ||
| + | * ... | ||
== Review == | == Review == | ||
| Line 29: | Line 42: | ||
=== Images === | === Images === | ||
| + | |||
| + | === Tables === | ||
=== Notes === | === Notes === | ||
Revision as of 09:03, 27 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 Guidelines
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).
Content
Article content should be restricted to fall within the scope of the page. This helps reduce overlap between pages and makes it easier for the reader to find the information that they are searching for. Keep in mind that shorter articles are more likely to be read. The wiki should focus on content specific to EMAC products and software. While it is important to provide background information and other instructions in-line with the article at times, it is often appropriate to refer to outside documentation such as man pages for this information, particularly when it can be assumed that most of the audience will already be familiar with the information.
Linking Other Documetation
When linking to other sites and documentation, it is important to use reliable sites with URLs that are relatively stable. For example, https://www.kernel.org/doc/man-pages/ for man pages. This helps reduces maintenance and ensures that the content on the pages that we link to is professional.
Style and Standards
Writing on this wiki should be clear, detailed, and concise; following standards of technical writing. This does not mean that the writing needs to be completely formal or dry, but it should be professional. The points below should be used as guidelines when writing and reviewing:
- Avoid wordiness and repetitive language.
- Use simple sentences where possible with smooth transitions between sentences and topics.
- Use the best word(s) to describe what you want to convey to the reader. Think, "Is there an easier way to say this?" This is challenging because much of the information is highly technical. Keep in mind that some of the audience may not be native English speakers.
- Avoid colloquialism and cliches.
- Be detailed and precise about the topic at hand, and leave out unnecessary details.
- ...
