Open Framework, Information Management Strategy & Collaborative Governance | Data & Social Methodology - MIKE2.0 Methodology
Wiki Home
Collapse Expand Close

Members
Collapse Expand Close

To join, please contact us.

Improve MIKE 2.0
Collapse Expand Close
Need somewhere to start? How about the most wanted pages; or the pages we know need more work; or even the stub that somebody else has started, but hasn't been able to finish. Or create a ticket for any issues you have found.

MIKE2:Manual of Style

From MIKE2.0 Methodology

Share/Save/Bookmark
Jump to: navigation, search
Open methodology framework logo.jpg
This article is a key aspect of the Open Methodology Framework and has therefore been protected. Propose changes to this article on its corresponding discussion page.

The MIKE2.0 Manual of Style is used to make the MIKE2.0 Methodology easier to read and understand by following a consistent format, set of naming conventions and taxonomy.

The MIKE2.0 Manual of Style used as its basis the Wikipedia Manual of Style, which also uses the MediaWiki software product to build written content in a collaborative fashion.

Whilst the goals of MIKE2.0 are different than Wikipedia, all guidelines from Wikipedia's Manual of Style are valid for creating content in the wiki aspects of MIKE2.0. The Wikipedia Manual of Style is far more comprehensive than that of MIKE2.0. Contributors should strive to follow these standards as best as possible to make MIKE2.0 easy to use.

There are currently a number of situations where the content in MIKE2.0 that was uploaded as part of the Baseline Release is inconsistent with the Manual of Style. The process of addressing these issues is currently underway.

Contents

Article titles

The main purpose of titles is to make it easy to find articles - not to build a content taxonony.

The title should appear as early as possible in the article - preferably in the first sentence. If possible, make the title the subject of the first sentence of the article as opposed to putting it in the predicate of the sentence or later in the article. For example, write "The MIKE2.0 Manual of Style is used to make the MIKE2.0 Methodology easier to read and understand" instead of "The MIKE2.0 Methodology is made to easier to read and understand through use of the MIKE2.0 Manual of Style".


The first time the article mentions the title, put it in bold using three apostrophes — '''article title''' produces article title. For example: "The MIKE2.0 Manual of Style is a style guide."

Headings

Use the == (two equal signs) style markup for headings, not the ''' (triple apostrophes) used to make words appear bold. Start with ==, add the heading title, then end with ==.

Capitalise the first letter only of the first word and of any proper nouns in a heading, and leave all of the other letters in lowercase.

  • Avoid links within headings. Instead repeat the word or phrase in the first sentence and wikify there.
  • Avoid overuse of subheadings.
  • Avoid "The" in headings;
  • If at all possible, avoid changing spelling of section titles, as other articles may link to a specific section.

Capital letters

American English and British English sometimes differ in their inclination to use capitals. Much of the MIKE2.0 content was written in Australia and the UK has therefore followed the British convention. Inconsistency in capitalisation is an area that can be improved across MIKE2.0 although it should be noted that capitalisation does not impact searches.

Initial capitals and all capitals should not be used for emphasis. Use italics instead.

Titles

Roles such as Data Steward, Data Modeller, or Solution Architect have generally been capitalized in MIKE2.0.

Technical Terms

Many technology terms are capitalised. This includes acronyms such as ETL as well as definitions of a specific practice area such as Data Warehousing.

MIKE2.0 Terms

Some MIKE2.0 terms are capitalised that would not be capitalized if they are not used in the MIKE2.0 context. Examples include words such as Phases, Activities and Tasks of the Overall Implementation Guide.

Italics

Italics are mainly used to emphasize words and should be used with discretion as to avoid distracting the reader.

Cases where italics would be used most frequently with MIKE2.0 include:

Titles

Italics are used for the titles of referenced works. (The titles of articles, chapters, and other short works are not italicized but are enclosed in double quotation marks.)

MIKE2.0 Terminology

MIKE2.0 introduces some unique terms, for example Information Development, which are often italicized if they are not linked.

Punctuation

Articles in MIKE2.0 generally follow the usual rules of English punctuation. A few points are explained below where MIKE2.0 may differ from usual usage are as follows:

Quotation marks

The best approach is to use "double quotes" for most quotations— they are easier to read on the screen—and use 'single quotes' for nesting quotations, that is, "quotations 'within' quotations'".

Contractions

In general, formal writing is preferred. Therefore, avoid the use of contractions — such as don't, can't, won't, would've, they'd, and so on — unless they occur in a quotation.

Slashes

Avoid joining two words by a slash, as it suggests that they are related, but does not say how. Spell it out to avoid ambiguities. Also, the construct and/or is awkward outside of legal writing. Use "x or y, or both," to explicitly conjoin with the inclusive or, or "either x or y, but not both," to explicitly specify the exclusive or.

These guidelines for Punctuation are a subset of those same as within the Wikipedia Manual of Style.

Acronyms and abbreviations

As MIKE2.0 is a methodology for technology implementation, it involves use of a very large number of acronyms.

Do not assume that your reader is familiar with the acronym or abbreviation you are using. The standard writing style is to spell out the acronym or abbreviation on the first reference (wikilinked if appropriate) and then show the acronym or abbreviation after it. This signals to readers to look out for it later in the text and makes it easy for them to refer back to it. For example: Enterprise Application Integration (EAI) technologies are typically used for application integration. There are a number of vendors that focus on building EAI products.

This approach is also important as there are often overlapping acronyms, e.g. BPM (Business Process Management, Business Performance Management)

MIKE2.0 also provides a Glossary, which is used for defining acronyms. Please add to this list if your acronym is not in the list.

Usage and spelling

Avoid self-referential pronouns

MIKE2.0 is developed in a community fashion and therefore articles must not be based on one person's opinions or experiences. Thus, "I" should not be used except, of course, when it appears in a quotation. Providing quotations can be a good approach for expressing individual opinion (which is valid) although keep in mind that talk pages exist for personal opinion. In addition, it is perfectly valid for a solution approach to have multiple options - all authors do not have to come to a complete agreement on a single approach.

Nevertheless, it is sometimes appropriate to use "we" or "one" when referring to an experience that anyone, any reader, would be expected to have, such as general perceptual experiences.

It is also acceptable to use "we" in describing a technical process; for example: "To improve data quality, we should standardize the data before correcting it.

National varieties of English

As with Wikipedia, MIKE2.0 will try and accommodate the various national varieties of English. The Wikipedia approach is summarised below:

Guidelines

  • Articles should use the same dialect throughout.
  • Where varieties of English differ over a certain word or phrase, try to find an alternative that is common to both.
  • If no such words can be agreed upon, and there is no strong tie to a specific dialect, the dialect of the first significant contributor (not a stub) should be used.

Impact of differences

Most importantly, the varieties in the English language are minor in terms of their impact on a user's ability to understand the content in MIKE2.0. Users should not get overly-focused on these differences - the technical problems around Enterprise Information Management are hard enough! There is some discussion regarding moving MIKE2.0 to "American English" due its primarily technical focus. Based on feedback, these changes may be incorporated into future releases. In this case, this Style Guide will change and a reference guide providing American standards for words will be defined to assist MIKE2:Contributors.

Images

Some general guidelines which should be followed in the absence of a compelling reason not to:

  • Left-alignments should be used for icons
  • Icons should be defined as thumbnails
  • When using multiple images in the same article, they can be staggered left-and-right
  • Generally, right-alignment is preferred to left- or center-alignment (except in the case of icons)
  • Use captions to explain the relevance of the image to the article
  • Icons don't require captions
  • Reference the comprehensive guide to image formatting in Wikipedia

The current image markup language is more or less this:

[[Image:image_file_name|captioning|size (in px)|alignment|caption title]]

Captions

Images should have captions unless the graphic is an unambiguous depiction of the subject of the article. Captions should be brief and are usually a a single sentence or a sentence fragment.

Icons do not use captions of the SAFE Architecture that shows strategic conceptual components, such as Foundation Capabilities for Information Development do not use captions.

Formatting

Keep markup simple

As recommended in the Wikipedia Style Guide, use the simplest markup to display information in a useful and comprehensible way. Markup may appear differently in different browsers. Use HTML and CSS markup sparingly and only with good reason. Minimizing markup in entries allows easier editing.

In particular, do not use the CSS float or line-height properties because they break rendering on some browsers when large fonts are used.

Legibility

Consider legibility the of what you are writing. Make your entry easy to read on a screen. Make judicious use of devices such as bulleted lists and bolding.

Spacing

Spacing can be an effective tool to improve Legibility. Spacing between sections in MIKE2 follows these general guidelines:

  • Level 2 Heading: 3 blank lines following
  • Level 3 Heading: 2 blank lines following
  • Level 4 Heading: 1 blank lines following

Remember that you will need to add 1 blank to create a break between sentences. Bulleted text does not wrap and you do not need to add a blank line.

Bulleted items

The following are rules for using lists of bulleted items:

  • When using complete sentences, always use punctuation and a period at the end.
  • Incomplete sentences don't need terminal punctuation.
  • Do not mix sentence styles; use all complete sentences, or use all sentence fragments.
  • Each entry begins with a capital letter, even if it is a sentence fragment.

Formatting issues

Formatting issues such as font size, blank space and color are issues for some style sheets and should not be dealt with in articles except in special cases. Typically, the usage of custom font styles will

  • Reduce consistency - the text will no longer look uniform with typical text;
  • Reduce usability - it will likely be impossible for people with custom stylesheets (for accessibility reasons, for example) to override it, and it might clash with a different skin as well as bother people with color blindness;
  • Makes pages fail (if the <font> tag is used);
  • Override default font settings in browsers.

There is also the possibility that other contributors will see a custom font style and starting a debate about it for aesthetic purposes. For such reasons, it is typically not good practice to apply inline CSS for font attributes in articles.

In summary, although supported by MediaWiki, please do not change font size.

Color coding

Dp not use color coding as an exclusive means to convey information. This is because this information not accessible to people with color blindness, viewing articles on black-and-white printouts, older monitors with fewer colors, monochrome LCD displays, PDAs, cell phones, and so on.

It is certainly acceptable to use color as an aid for those who can see it to supplement the overall approach, but the information should still be accessible without it.

Wikilinking

The use of links to other MIKE2.0 articles, for example, [[Information Maturity QuickScan]] , is encouraged. Use the links for all words and terms that are relevant to the article.

The standards recommended by Wikipedia also apply to MIKE2.0. These are summarised below (edited to refer to MIKE2.0 topics as opposed to Wikipedia):

Linking Guidelines

Make sure that links relevant are relevant to the context of an article and do not over-link articles to the point where they are distracting to reading the article. Links should be seen as a way for a reader to get more detail about a certain area (if needed) but not something that is mandatory to click on.

Whereas each MIKE2.0 article will stand on its own, there is a natural dependency between articles as part of a methodology that is more significant that in wikipedia.

Overlinking

Whilst its important to link Articles, it is possible to link too much. An article may be considered overlinked if any of the following is true:

  • more than 10% of the words are contained in links;
  • it has more links than lines;
  • a link is excessively repeated in the same article; however, duplicating an important link distant from a previous occurrence is appropriate;
  • more than 10% of the links are to articles that don't exist

As a general rule, do not put links in the title; however, this may be acceptable with complex titles or verbose leads, such as those concerning multiple concepts.

Form

Links that follow the proposed Naming Conventions are much more likely to lead to existing articles. When there is not yet an article about that subject, good links will make the creation of a correctly named article much easier for later Contributors.

It is possible to link words through a piped link that are not exactly the same as the linked article title — for example, [[Enterprise Application Integration |EAI]] shows up as EAI in rendered text but links to the article on Enterprise Application Integration. However, make sure that it is still clear what the link refers to without having to follow the link.

When forming plurals, do so thus: [[language]]s . This is clearer to read in wiki form than [[language|languages]]  — and easier to type.

Context

While editing, use preview to check a link and to see if it exists. There may be alternate spellings of the link as well, so it can helpful to do a search for articles of similar names.

Links should use the most precise target that arises in the context, even when this is merely a simple redirect to a less specific page title such as a Disambiguation page. For example, link to " [[data quality]] " rather than " [[data]] quality".

Including Technical Content in the MIKE2.0 Wiki

Although the wiki is not the location for hosting Software Assets developed as part of MIKE2.0, sometimes code snippets may be used on the site to help describe a concept.

When providing technical examples in the wiki, it is necessary to maintain clarity and simplicity. Not only does this result in a more professional look, but it prevents the reader from becoming confused. For example to show a sample SQL statement, SQL should be broken across lines to improve legibility. If it is typically an administrator function, specify this in describing its usage.

 SELECT *
 FROM Customer
 WHERE (Customer.customer_id LIKE '12345678')

Commenting the code is helpful as an introduction to how the code is to be used and to describe why the author has included the code snippet.

Wikipedia also has code snippets on the site and its guidelines are equally valid to apply to the MIKE2.0 wiki - a Wikipedia sub-manual to its Manual of Style shows how to represent command line examples.

Using Disambiguation Pages

Open methodology framework logo.jpg
This article is a key aspect of the Open Methodology Framework and has therefore been protected. Propose changes to this article on its corresponding discussion page.

Disambiguation pages are solely intended to allow users to choose among several articles, usually when a user searches for an ambiguous term. Disambiguation pages are important as an article is uniquely defined in a namespace by its article name and sometimes the same name can apply to different concepts.

Wikipedia provides recommendations on Disambiguation and these guidelines apply equally for MIKE2.0. Wikipedia also provides a template structure that is intended to make this process more efficient by giving disambiguation pages a consistent look and avoiding distracting information, such as extraneous links (internal or external). It applies to pages containing only disambiguation content, whether or not the page title contains the word "(disambiguation)".

The primary use for Disambiguation in MIKE2 will involve situations with:

Disambigation pages should be used sparingly when describing solution options, it is preferred this be contained within MIKE2.0 Solutions. Disambiguation pages may sometimes be created as temporary measures for bringing together solution options before eventually being merged into the overall solution approach.

Disambiguation pages should be defined simply by creating an article page with the term name and providing links to ambiguous terms.

Using Categories

Open methodology framework logo.jpg
This article is a key aspect of the Open Methodology Framework and has therefore been protected. Propose changes to this article on its corresponding discussion page.

Categories are the major topics covered by an article. Categories provide a useful mechanism for readers to find an article within a classification scheme. All articles should have at least a single Category.

Using Categories, users can find articles based on their area of interest in a fashion that is oftentimes more effective than using search terms. It also helps readers to find similar articles.

Category Concepts

Categories are simply used to make it easier to find articles and to relate them to one another. MIKE2.0 articles can appear in more than one category and each category can have more than one parent category.

Categories do not form a strict hierarchy or tree structure, but form what is generally referred to as a directed acyclic graph. For a more detailed description of Categories, refer to the article on Categorization on Wikipedia.

Implementing Categories

Adding Categories to Article Pages

Categories are added to articles by including the following text to the top of the Article: [[Category Name]]

An example can be seen by looking at existing Category pages.

Creating New Categories

Contributors can easily add Categories to their articles and create new Categories if they do not exist. Adding a Category tag to an article (as shown above) that does not exist automatically creates a new Category.

Contributors that create new Categories should add a description of the Category on the Category Page. This can include links to other articles that describe the Category in better detail. An example of Category Page descriptions can be seen by looking at Tools and Technique Papers.

The recommendations put forward on Wikipedia for using, creating and editing categories are well-defined. They provide a good set of guidelines for what can be an imprecise science related to the classification of articles and organizing categories.

Sub-Categories

Sub-categories are children of parent Categories. They are useful for organising content at more granular levels of detail under a major category heading.

Sub-categories are created by simply adding the name of the parent category to category page of child category. For example, the add Category:Architecture Design Patterns as a child of the Category:SAFE Architecture, the following text is added to the category page:

[[Category:SAFE Architecture]]

Although Sub-Categories are members of a parent it should be noted that the category scheme as a whole does not form a tree. Each article can appear in more than one category, and each category can appear in more than one parent category.

To see an example of a category with multiple sub-categories, refer to Category:SAFE_Architecture.

Category Extensions in the MIKE2.0 Wiki

Category Browse Extension

The CategoryTree extension provides a dynamic view of the MIKE2.0 wiki's category structures as a tree - it uses AJAX to load parts of the tree on demand. This allows users to more easily see the list of article by category and their relationships.

Category Select

This extension makes it possible to select categories from a "tag cloud" of all available categories as opposed to having to manually write the category name..

currently under development which will make it possible to add new categories to article pages through a drop-down list as opposed to manually writing in the category

Category Suggest

This extension makes the category dynamically appear as it is typed by named as opposed to having to manually write the category.

Integration with Social Bookmarking

This extension enables bookmarked articles to be integrated to the content developed in a wiki through the use of common categories. This functionality is provided by an extension to the Scuttle Social Bookmarking tool.

Using Talk Pages

Open methodology framework logo.jpg
This article is a key aspect of the Open Methodology Framework and has therefore been protected. Propose changes to this article on its corresponding discussion page.

Talk Pages provide a dicussion forum that is specific to an article. For guidelines on using Talk Pages, refer to the detailed instructions on Talk Pages on Wikipedia

In terms of the MIKE2.0 Methodology, there are 3 key issues related to the use of Talk Pages.

  1. Peer Reviews are initiated through Talk Pages. When an author want to conduct a Peer Review, they should place the Template:Peer review into an article's Talk Page using the following text: [[MIKE2 Peer Review }]]
  2. Talk Pages allow for forum discussions to take place on Protected Content. This means that all Contributors can provide feedback on any article. These forum discussions are the key mechanism for recommending changes that will go into each Release Cycle.
  3. Dicussions can take place at an point in the lifecyle of an article and should be specific to release recommendations or as part of a peer review.

Because some MIKE2.0 follows a release cycle for articles that are part of the Core MIKE2.0 Methodology, the use of Talk Pages is arguably even more important than on Wikipedia.

Using Templates

Open methodology framework logo.jpg
This article is a key aspect of the Open Methodology Framework and has therefore been protected. Propose changes to this article on its corresponding discussion page.

Templates are used in MIKE2.0 to duplicate the same content across more than one page. You can change a template in one place and it will immediately propagate to the pages that use it. This process is called transclusion.

Although it does not contain the library of templates available in Wikipedia, the cases where templates would be used in MIKE2.0 is the same as the process described in Wikipedia. At this stage, the primary use for templates in MIKE2.0 is for recurring messages that are used to denote pages being in the process of construction or being reviewed.

To transclude a Template Page directly into another, the following text should be used:


{{Template Page Name}}
. Examples of transcluded Template Pages can be found by looking at the pages under construction

Transclusion in a general sense is also used to bring in text from a single page into a composite page. The syntax for bringing articles in differs slightly in that a colon is pre-fixed in front of the page name:


{{:Page Name}}
. The Manual of Style transcludes provide a good example of transclusion into the overall document.

A list of Templates can be found by referencing the Template Namespace.

Wiki Contributors
Collapse Expand Close