From Ingres Community Wiki

Contents 1 Ingres Style Guide Purpose 1.1 Ingres Style Guide Status 2 Basic Ingres Article Guidelines 2.1 Page Titles 2.2 Section Headings 2.3 Article Tone and Structure 2.4 Detailed Style Issues 3 Ingres Wiki Categories 4 Ensure the Article Is Easy to Locate 5 Presenting Usable Technical Material 5.1 Documenting Commands and Code Syntax 5.2 Writing Clear Procedures 5.3 Explaining How Things Work with Processes 6 Where to Find More Style and Writing Help

Ingres Style Guide Purpose

Content on the Ingres Community Wiki should follow a style that enhances the information's effectiveness. Guidelines may vary depending upon the purpose of the content. For example, wiki articles written to demonstrate the use of Ingres syntax in application development environments may not follow the same guidelines as Ingres Engineering for articles describing the proposed implementation of a new feature. However, all content should follow some common guidelines.

Having a standard for content will help to improve the usability and readability of the Ingres Community wiki.

Ingres Style Guide Status

The Ingres Community wiki Style Guide is a work in progress and is subject to change as content and standards evolve.

Last Updated: 28 Apr 2010

Basic Ingres Article Guidelines

Style and formatting should be consistent within a Ingres article, although it necessarily may not be throughout the Ingres Community wiki.

Writing should be clear and concise. Articles should introduce readers to topics, remind them of what they may have forgotten, or detail development projects. Plain English works best; avoid jargon, vague phrases, and unnecessary complexity.

Before creating content on the Ingres Community wiki, think through the purpose of the content you are providing. Consider how you would search for this content if you were unsure whether it already existed. Identify clearly what you want the reader to get from the article. For example, a user may not know what the iipmhost command does; instead, include a text description of the command: "Echo Name of Host -- iipmhost Command."

For technical articles, do not make any assumptions regarding the knowledge of the reader. Examples and pictures can speak a thousand words.

Page Titles

When naming your page, keep the following points in mind. (Most of them apply to the body of the page as well.)

• Make page titles unique and specific. They should match the article content.
• Use upstyle capitalization, the preferred style. In upstyle titles, the first and last words and all nouns and most other words are capitalized except for articles (a, an, the) and prepositions (in, by, on, with, at, and so on). In downstyle capitalization, only the initial word and proper nouns are capitalized.

Upstyle: "Ingres New Features per Release".

Downstyle: "Ingres new features per release".

• Avoid special characters such as the slash (/), plus sign (+), braces ({ }), and square brackets ([ ]). Use "and" instead of an ampersand (&), unless the ampersand is an accepted part of a name.
• Use spaces between words when creating the wiki page title (do not use CamelCase). The wiki page title should appear as any article title does.

Section Headings

The previous guidance for page titles also applies to section headings.

• Section headings provide an overview in the page's table of contents and enable readers to navigate the text more easily.
• Headings should be unique within a page; this applies even for the names of subsections.
• Break content into well structured sections using wiki heading formatting:
  • The page title is considered to be the main section heading; therefore, do not use =H1= for section headings.
  • The first section heading within the body of your article should use ==H2==.
  • Headings should be formatted using ==H2==, followed by ===H3===, ====H4====, and so on.
• There is no need to use the triple apostrophes (' ' ') to make the section header boldface.
• It is good practice to leave a comment on a section heading if you know another article links to it. This is helpful in the rare case where a section heading is updated (the linking article will also need to be updated). For detail on adding a comment, see Help:Contents#Adding a Hidden Comment to Your Wiki Page.

Article Tone and Structure

Write to be understood, to make reading easier. Address readers directly, using second person ("you").

Summarize the purpose of the article in the opening paragraph.

Beyond the first paragraph, try to follow these tips:

• Use brief paragraphs.
• Cover only a single topic in each paragraph.
• Use plain English.
• Be clear, concise, and unambiguous.
• Use active voice ("You can do xxx," not "Xxx can be done by users.")
• Provide references where readers can find more information about the topic.
• Avoid abbreviations when they might be confusing or interrupt the flow of information. (See below.)
• Be consistent with technical terminology; always use the same term for an item and do not use variations for the sake of variety.

Detailed Style Issues

For help with wiki editing, see Help: Editing.

Abbreviations, Contractions, and Acronyms

Different dialects of English handle abbreviations and contractions differently. Be consistent throughout the article, and maintain the original contributor's chosen style.

Note: Ingres user documentation does not use contractions (such as "doesn't").

Always explain acronyms and abbreviations when they are first used. At the first occurence, the acronymn should be contained in parentheses. For example, if the article is discussing Extract Transfer and Load tools, then the first usage would be "Extract Transfer and Load (ETL) tools." After this, you could use the abbreviation "ETL."

Spelling

Spelling is an issue that often becomes contentious because of multiple contradictory standards, for example, British English, Australian English and American English. Use a consistent spelling standard throughout an article. Follow the spelling standard of the article subject or that of the first author of the article to avoid discrepancies within an article.

Note: Ingres user documentation adheres to American usage.

HTML Markup Within Articles

Within any article, using HTML markup should be a last resort. Always prefer wikicode, particularly when using elements such as bold or italics.

Links Within Articles

In an article, when linking content, be specific in your link title. Do not reference a generic title such as "here". For example,

Correct: The Ingres wiki is at Ingres Community Wiki.

Incorrect: The Ingres wiki is here.

Ingres Wiki Categories

You should add category tags at the bottom of each article. For a complete guide of Ingres Categories see Special:Categories. If you add a new Category, update it within a description of the content to be categorized.

For more information about using categories on the Ingres Community wiki, see Purpose of Categories.

Ensure the Article Is Easy to Locate

Consider the following points to ensure readers can locate your article easily using a search engine.

• Use clear and detailed titles.
• Repeat targeted keywords.
• Use section headers.
• Repeat content where necessary. This is especially true when providing articles or examples for a component that is widely used. For example, because there are many databases, content must be specific to our technology. Use the keywords Ingres or OpenROAD as appropriate.
• Ensure page titles are not created using CamelCase styling; search engines treat the title as one word when no spaces are included in the title, making it difficult to locate content.

Presenting Usable Technical Material

Articles that contain technical material should be as clear and straightforward as possible. Here are abbreviated standards that the Ingres Technical Publications Department uses to create the following kinds of information elements:

• Commands and code syntax
• Procedures
• Processes

Note: Processes and procedures are similar but not identical. A process defines and explains a series of events, stages, or phases. A procedure defines a series of steps a user can perform using a given product to accomplish a particular task.

Documenting Commands and Code Syntax

A code element identifies commands or code syntax and definitions. Code elements can be input at a command line or interface, or they might exist as part of a configuration file or other code sample.

Code elements always include the following:

• Heading -- Explains the purpose of the code.
• Introduction -- Briefly explains the purpose of the code segment. For commands, this introduction should focus on why the user would want to use the command.
• Syntax -- Identifies the syntax for the command, including parameters and special characters.
• Example -- Helps users understand typical code usage and command syntax. Annotating examples further promotes comprehension.

Writing Clear Procedures

A procedure element is a defined set of steps that guide users to accomplish a particular task. A step should have one clear, complete action and one result.

For example, procedures give instructions about using the product, such as a sequence of inputs in a GUI, how to log on to a system, how to install OpenROAD, and so on.

Procedure elements always include the following:

• Heading -- Use the infinitive form of an action verb: "Start Ingres Visual Manager". Do not use a gerund ("ing" word, such as "Starting").
• Introduction -- Explain why users would want to perform the procedure.
• Procedure subheading -- Introduce the numbered steps. Use the word "To" and then the action verb from the heading: "To start Ingres Visual Manager". Make the subheading bold and do not end it with a colon.
• Steps and results -- Number the steps, which should each begin with an action verb: "1. Click Start, All Programs, Ingres...". Follow each numbered step with an unnumbered result: "The Ingres Visual Manager is opened."

Explaining How Things Work with Processes

A process element explains a series of events, stages, or phases. Processes tell the audience what happens in the flow of events or how something works. Processes can also describe a set of procedures.

Processes can be categorized into the following types of flow representation. The type of flow should be stated or implied.

• Linear
• Branching
• Cycles
• Cause and effect

Process elements always include the following:

• Heading -- Briefly describes what the process explains. Always begin process element headings with "How."
• Introduction -- Explains why the process is relevant to the reader.
• Steps -- Process steps should fully explain each aspect of the process including, if appropriate, definitions, code, and results.

Where to Find More Style and Writing Help

The below professional (and free) online style guides can be a benefit when composing content.

• Wikipedia Manual of Style -- Addresses many wiki writing issues.
• Wikipedia -- Make technical articles understandable.
• The Chicago Manual of Style by the University of Chicago Press staff.