Style Guide

From oacwiki

This style guide shows you how to edit the OpenAccess public wiki. For the OpenAccess Wiki, we have just a few style guidelines for formatting within pages.

1 MediaWiki User Guide

The OpenAccess Wiki is based on MediaWiki, the same software that runs Wikipedia. See the MediaWiki Help Page for general information on how to edit, create pages and manage your user settings.

2 Use Effective Titles, Headings and Link Text

Clear and relevant page title, section headings and link anchor text make your page engaging and informative to your human readers, plus they improve its search engine placement. Write Content to Get Better Search Engine Placement] tells you how to write these important elements of your page, using this wiki as an example. Portions of this style guide were adapted from this article by John McGehee.

3 Templates

MediaWiki Templates transclude the content in the template into the the calling page, just like #include. The following "Conventions" section is in a template named Template:Conventions that is inserted into this document using:

{{Conventions}}

Templates are used extensively for the portions of the oaScript documentation that are common to all scripting languages.

You can see a list of all currently existing templates in Special:AllPages. Specify Display pages starting at Template:.

4 Conventions

4.1 Typography

Monospace
in a box

For guidelines on editing wiki pages yourself, see the Style Guide.

Now let's look at how you write Wikitext to produce this typography.

4.2 Commands, File Names, Literal Text Input or Output

Format command names, file names or other text intended to be entered literally, or which appears in the output stream, with the <tt> tag. For example,

 The <tt>def2oa</tt> command reads a DEF file and converts it to OpenAccess.

renders as:

The def2oa command reads a DEF file and converts it to OpenAccess.

4.3 Computer Language Source Code

When mentioning computer code in a sentence, use the <code> tag. For example,

 Open designs with the <code>oaDesign::open()</code> method.  

renders as:

Open designs with the oaDesign::open() method.

Note how the code is rendered with a colored background.

Since there is so little difference between the rendering of <tt> and <code>, it is fine if you do not care to distinguish between them.

4.4 Text to Be Substituted

Format text to be substituted with text provided by the reader using ' ' (two single quotes). This often appears within <tt> or <code> tags. For example,

 Create file ''lefFile'' from library ''libName'' using the command
 <tt>oa2lef -lef ''lefFile'' -library ''libName''</tt>

renders as:

Create file lefFile from library libName using the command oa2lef -lef lefFile -library libName

4.5 Multi-Line Code Examples or Output

To give a multi-line example of code or program output, simply indent it with two spaces and it will be rendered like this:

 public void CreateAllDesigns()
 {
   oaNameSpace.push(ns_);
   CreatePinDesign();
   CreateInvDesign();
   CreateMidSchematicDesign();
   oaNameSpace.pop();
 }

Use two spaces for each further indentation.

5 Starting a New Page

If you want to add content that does not fit in an existing wiki page, start a new page. Most editors use the WikiLinks method to create a new page.

If you like, start your new page with the WikiText in the Boilerplate page. It has examples of all the style guidelines mentioned here.

5.1 Title

A descriptive, accurate title that fully describes the content is the most important thing you can do to help users find your page. The title will appear as the first line of a search result in a search engine. If the nature of the content changes, change the title to match using the move command at the top of the page.

5.2 First Sentence

Make the first sentence a one sentence abstract. The first sentence of the page is most often (but not always) the next thing that appears in your search result. It should show the reader that this page contains the answer.

5.3 Sections

Start with section level 2 (== Heading Title ==) and maintain proper section hierarchy. Do not use section level 1 (= Heading Title =). Clear, descriptive section headings make for a useful table of contents, which readers will scan when they land on your page. Section headings are prominent to search engines.

5.4 Categories

MediaWiki categories provide automatic indexes of related content. Readers can see a list of pages on the same topic by clicking on the category displayed at the bottom of the page.

When you edit a page, add a category tag at the top of the page. For example:

 [[Category:Scripting Languages]]

Every page must be a member or one or more categories. If you do not know what category to use, or you just don't care, category OpenAccess will do:

 [[Category:OpenAccess]]

Templates themselves can be categorized without affecting the pages that call them by putting the category link inside a <noinclude> tag:

  == Conventions ==
  <noinclude>[[Category:Administration]]</noinclude>
     ...

Putting the category after the section heading as shown avoids excess vertical spacing above the template.

You can see a list of all the current categories by clicking on Browse Categories in the menu at left.

Categories are arranged in a hierarchy, with category OpenAccess at the top.

5.5 Boilerplate for a New Page

The Boilerplate page contains examples of all the style guidelines mentioned here. You can use it as a starting point for your new page.