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.

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

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.
• ...

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.

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.

Document Structure

Document structure may vary according to the article type (i.e. procedure, informational, etc), but structure should be consistent across pages of similar type. Some common elements to include are:

1. Introduction: This generally is a couple of sentences at the top of the article before the first second-level heading. Describe what information the page covers.
2. ...

For procedures:

1. Introduction
2. Required Tools (material, etc)
3. Procedure
4. Next Steps
5. ...

Images

Consistent formatting and layout of images is important across the wiki, but not every image will fall under the same formatting rules. This section provides some general guidelines for image formatting and usage across the wiki.

Usage

Images such as screen shots can add clarity to a complex description. Here are a few guidelines to using images appropriately:

1. Insert images where practical to add a visual element accompanying the text. On procedures using GUI applications, screen shots can be helpful for all non-obvious steps, particularly the first reference to a menu.
2. All images used within a page should be referenced in the text by figure number.
3. All images used within a page should have a visible caption including the Figure number and a descriptive title of the format: "Figure n: Image Title".

Size and Readability

Images should be displayed large enough to display the detail required based on the usage in the document reasonably well. Clicking on the image will take the user to the full resolution image as well, but this should not be relied on as an excuse for images that are not usable inline with the document. Along with this, images should not disrupt the flow of the document or cause the page to scroll left or right when viewed with a monitor of 1024x768 resolution. A display width of 500 pixels or less is generally appropriate for most screenshots and other images. If sufficient detail is not visible at that size, it may be necessary to crop the image so that the relevant information has sufficient focus.

Display Format and Text Flow

Ideally, the text related to an image should flow around the image without breaking. This is particularly useful for step-by-step procedures where several steps refer back to the same image. Early on in the development of the wiki, the frame mediawiki format was used for images to allow the images to be displayed with the caption present. However, this format is limited in alignment and text wrapping. It was determined that the thumb format should be used instead of frame. The downside to using this format is that the desired size of the image must be specified explicitly in the wiki code to prevent the default thumbnail size from being displayed.

When an image is part of a process or description, it should be right aligned with related text wrapping to the left. The code below demonstrates the proper wiki syntax for inserting an image.

[[File:My Image.png|right|thumb|500px|Figure 1: The First View of My Product]]

After the image and associated text, floating may need to be broken before the next image or section heading. There are several ways to do this, but the code below seems to work well.

<div style="clear: both"></div>

Tables

Tables used as part of an article should follow these rules:

1. Use a caption in the first row of the table that includes the table number as well as a descriptive title in the form "Table n: Descriptive Title".
2. All tables should be referred to in the text by table number.
3. Each column should have a descriptive heading. This applies to row labels as well when applicable.

Messages

Notices, warnings, and other informational messages are an important tool to highlight important information within a page. The "mbox" (message box) family of templates should be used to format and display these messages. The templates are capable of determining how the box should be formatted based on context of its use. Also, the "type" passed to the template will determine what image is displayed. Some of the most common types used in this project are:

More detailed documentation on usage can be found here: Template:Mbox/doc

Some important points regarding message box usage:

1. Use message boxes to highlight important pieces of information.
2. Overuse of message boxes within an article make the message less effective and disrupt the flow of the article. In these cases it is important to evaluate if the information should be included more in-depth in the article. An exception would be a "Safety" section which would be comprised mainly of important / warning messages.
3. Keep the information in message boxes concise. Do not use them to explain concepts or processes, only to highlight important points and information. The detail should be provided in the article text.

Code Blocks

Code blocks are used to display example source code and console sessions. There are several ways to do this in mediawiki syntax, including indenting lines, and using <code> tags. The preferred and most flexible method is to use the SyntaxHighlight extension. This works more smoothly when nested in other elements (i.e. lists) and allows for language-based syntax highlighting among other features. In general, use <code> tags when you need to add a single word or phrase within the text. Use <syntaxhighlight> tags when you need demonstrate a block of commands, code, console output, or system text such as configuration file contents.

Using the SyntaxHighlight Extension

Documentation for the SyntaxHighlight GeSHi plugin can be found here. This includes usage, syntax, and available languages. The c and bash languages are sufficient for most code used in this wiki, but bash syntax highlighting of console command output is not desirable. To get around this, EMAC made some modifications to the extension to allow for console language highlighting and combining adjacent syntaxhighlight blocks into the same display element.

The following is an example of code that illustrates one of the issues of using bash as the language for console output. Notice the highlighting of the file named "test" as a bash language keyword:

<syntaxhighlight lang=bash>
root@emac-oe:~# ls /root
.  myfile yourfile test
</syntaxhighlight>

root@emac-oe:~# ls /root
.  myfile yourfile test

Using the bash language for the initial command followed by the console language for the output is illustrated below:

<syntaxhighlight lang=bash>
root@emac-oe:~# ls /root
</syntaxhighlight><syntaxhighlight lang=console>
.  myfile yourfile test
</syntaxhighlight>

root@emac-oe:~# ls /root

.  myfile yourfile test

Lists

Bulleted and numbered lists are common elements in this project. Some of them may be large with multiple levels and nested elements (procedures, for example). While standard mediawiki syntax provides controls for lists, support for nesting elements (code blocks, notes, images, etc) is limited. To get around these issues, the ComplexList extension has been installed and should be used for most lists, though standard mw syntax is still acceptable for simple lists.

Using the ComplexList Extension

ComplexList elements begin with a <cl> tag. The style of numbering (1, 2, 3; a, b, c; i, ii, iii; etc) is specified on the first line of a level, and new levels are denoted by indenting the line. Here is an example as taken from the ComplexList extension page:

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.