From Open Sustainability
|
| This article is a key part of enabling an Open Methodology Framework. Eventually, it will be protected and changes will be proposed on its corresponding discussion page. For now, anyone can change this article.
|
The Manual of Style outlines a consistent format, set of naming conventions and taxonomy for the FISDev. If followed, the manual of style will make the FISDev easier to read and understand.
This Manual of Style builds off the Wikipedia Manual of Style, which also uses the MediaWiki software product for building written content in a collaborative fashion.
Whilst the goals of FISDev are different than Wikipedia, all guidelines from Wikipedia's Manual of Style are valid for creating content in the wiki aspects of FISDev. The Wikipedia Manual of Style is far more comprehensive than that of FISDev. Contributors should strive to follow these standards as best as possible to make it easy to use.
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 FISDev Manual of Style is used to make the FISDev Methodology easier to read and understand" instead of "The FISDev Methodology is made to easier to read and understand through use of the FISDev 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 FISDEV 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 Open Methodology 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 FISDEV 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 Sustainability Steward or Solution Architect have generally been capitalized in FISDEV.
Technical Terms
Many technology terms are capitalised. This includes definitions of a specific practice area such as Sustainable Development.
FISDev Terms
Some FISDev terms are capitalised that would not be capitalized if they were used in a general 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.
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.)
Unique Terminology
FISDev refer to some unique terms, for example Information Development, which are often italicized if they are not linked.
Punctuation
Articles generally follow the usual rules of English punctuation. A few points are explained below where the approach 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 FISDev is a methodology for sustainability implementation, it involves use of a 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. This approach is also important as there are often overlapping technology acronyms.
FISDEV 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
FISDev 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, FISDev 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 FISDev. Users should not get overly-focused on these differences. In this case, this Style Guide will change and a reference guide providing American standards for words will be defined to assist FISDEV: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 FISDEV Architecture that shows strategic conceptual components, such as Foundation Capabilities for Sustainable 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
Do 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 FISDev articles, for example,
[[Sustainability 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. These are summarised below (edited to refer to FISDEV 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 FISDev 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,
[[Sustainable Development |SD]] shows up as SD in rendered text but links to the article on Sustainable Development . 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 "
[[Sustainable Development]] " rather than "
[[Sustainable ]] Development".
Including Technical Content in the FISDev Wiki
Although the wiki is not the location for hosting Software Assets developed as part of FISDEV, sometimes code snippets may be used on the site to help describe a concept.
Using Disambiguation Pages
|
| This article is a key part of enabling an Open Methodology Framework. Eventually, it will be protected and changes will be proposed on its corresponding discussion page. For now, anyone can change this article.
|
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 FISDEV will involve situations with:
- Articles that define common acronyms that have different meanings
- Differing definition of a solution to a problem that is contained across Supporting Assets
- Terms which have differing (but similar) definitions in the industry
Disambiguation pages should be used sparingly when describing solution options, it is preferred this be contained within FISDEV 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
|
| This article is a key part of enabling an Open Methodology Framework. Eventually, it will be protected and changes will be proposed on its corresponding discussion page. For now, anyone can change this article.
|
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. 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 MIKE2.0 Derivative Work.
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:FISDEV Architecture, the following text is added to the category page:
[[Category:FISDEV 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:FISDEV_Architecture.
Category Extensions in the MIKE2.0 Wiki
Category Browse Extension
The CategoryTree extension provides a dynamic view of the 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
|
| This article is a key part of enabling an Open Methodology Framework. Eventually, it will be protected and changes will be proposed on its corresponding discussion page. For now, anyone can change this article.
|
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 Open Methodology, there are 3 key issues related to the use of Talk Pages.
- 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:
- 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.
- Discussions 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 FISDev follows a release cycle for articles that are part of the Core FISDev Methodology, the use of Talk Pages is arguably even more important than on Wikipedia.
Using Templates
|
| This article is a key part of enabling an Open Methodology Framework. Eventually, it will be protected and changes will be proposed on its corresponding discussion page. For now, anyone can change this article.
|
Templates are used in the Open Methodology 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 FISDEV is the same as the process described in Wikipedia.
To transclude a Template Page directly into another, the following text should be used:
{{Template Page Name}} . An example use of templates in FISDEV is for recurring messages that are used to denote pages being in the process of construction or being reviewed. 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.
