Wiki.emacinc.com:Style Guide

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 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:

1. Avoid use of first person when it relegates use of first person throughout the entire article.
2. Avoid use of first person when it sets an informal or unprofessional tone in the article.
3. 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:

1. 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).

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, but it is essential for readability.
• Avoid colloquialism and cliches.
• Be detailed and precise about the topic at hand, and leave out unnecessary details.
• ...

Content and Common Elements

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.

Review

As a wiki, the content on this site should be continually reviewed, improved, and expanded. As this information is provided to customers, it is important to review content for quality and accuracy. However, it is also important to ensure that the information becomes available to customers as quickly as possible. The FlaggedRevs Extension is installed to help with the review process and can be used to control which versions of a page are visible to customers based on their review status. The basic review policy for pages on the wiki should be:

1. All new pages or major additions should be reviewed by a different user, regardless of who did the writing.
2. Minor edits should not require review before release, but should be reviewed at some point by a different writer for quality improvement.

The "Edit Review" section under Special:SpecialPages contains links useful for determining which pages need to be reviewed. Default review levels for each user account and the extension will need to be set appropriately for this to be useful.