VERSION CONTROL

This section of the document records the various versions or releases of this document

[TOC]

1.      INTRODUCTION

1.1      Purpose

This document outlines a guideline for developing information technology standards for the Information Management Branch (IMB). Some of the steps in the process described here are suggested and some are mandatory.

1.2      Audience

This document is directed at those involved in the production of information technology standards for both the Ministry of Sustainable Resource Management and the Ministry of Water, Land and Air Protection.

1.3      Acknowledgments

The following people have provided valuable suggestions and criticism which have contributed significantly towards the development of this methodology:

1.4      Other Standards

The following standards or documents may be of interest as they provide more detailed information on this and related topics

Standards Template

Ministry Web Standards

[TOC]

2.      OBJECTIVES OF DEVELOPING SYSTEMS STANDARDS

The objectives of developing information technology standards at the Ministry are to:

• ensure consistency across the Ministry among a wide variety of information systems processes and products such as application systems deliverables, network architectures and systems operating procedures;

• clarify expectations of contracted staff and Ministry staff regarding the format and content of deliverables and services relating to the development, maintenance and operation of information systems and information systems infrastructures;

• lower overall systems development and maintenance, infrastructure development and maintenance and general operating costs;

• provide benchmarks and checklists for a wide variety of information systems activities such as systems development and systems maintenance, hardware and software installation and maintenance and quality assurance activities;

• ensure the quality of the Ministry's information systems;

• reduce training costs and shorten learning curves for users by giving operating systems, operating procedures and application systems and a consistent look and feel.

Standards should be useful, not onerous, to these efforts. They should be written in plain English, and organized and documented in a logical manner, with the rationale for each standard clearly explained.

The IMB will be responsive and cooperative in considering recommended changes to this document.

[TOC]

3.      ROLES AND RESPONSIBILITIES

This section outlines the various roles involved in the development of Information Technology standards in the Application Group.

3.1      Standards Coordinator

The Standards Coordinator is responsible for the following:

• working with the Standard Custodians to determine and track the overall status of Information Technology standards (what's required, what's in place, what's outstanding, priorities, estimated completion dates);

• keeping track of standards development activities on an ongoing basis;

• assisting the Standards Custodians to define the scope of each standard by ensuring that standards do not overlap or conflict and that there are no gaps in the standard;

• providing assistance and guidance to standards developers e.g., in interpreting and applying the standards for standards;

• signing off the standard from a standards perspective i.e. that the standard is developed according to documentation standards and following the methodology described in this document;

• ensuring that standards are communicated effectively;

• managing the Application and Data Standards web page and keeping the information up-to-date; and

• establishing and maintaining the standards governing standards.

The Standards Coordinator must be internal to the IMB.

3.2      Standards Custodian

The Standards Custodian is responsible for the following within his/her area of responsibility:

• ensuring that the required standards are identified, prioritized and developed;

• establishing standards development projects as required and ensuring they are completed effectively;

• ensuring that standards are updated on a timely basis;

• identifying whether standards under development should be posted to the Internet or the Intranet; and

• ensuring that the standards developed are signed off, communicated to the appropriate people and followed.

Standards Custodians must be internal to the IMB.

3.3      Standards Developer

The Standards Developer is responsible for the following:

• developing the content of a standard with input from subject-matter experts and key stakeholders;

• documenting a standard according to Application Group standards;

• ensuring that standards development activities follow the standards development methodology (see Section 7 and Section 8 for details of the process).

The Standards Developer may be an internal or external systems professional.

3.4      Subject-matter Expert(s)

The Subject-matter Expert(s) are responsible for:

• providing expert knowledge to guide the development of sound standards;

• outlining clearly the rationale for each standard; and

• signing off the standard for content and accuracy.

The Subject-matter Expert(s) may be an internal or external systems professional with expertise in the standard being developed. It is acknowledged that for emerging technologies it is difficult to find "experts" and that this role may be filled by someone with experience, not necessarily expertise, or by someone with academic expertise and little practical experience.

3.5      Key Stakeholders

Key stakeholders are those people affected by the standard e.g., people who have to use the standard and people who use products developed by the standard e.g., graphical user interface, requirements documentation. They are responsible for:

• providing requirements for standards; and

• reviewing proposed standards and raising any points of concern.

Key stakeholders may be internal or external to the Ministry

3.6      Application Manager

The Application Manager has overall responsibility for Application and Data standards, including establishing high-level priorities. This person is responsible for signing off all Application and Data standards.

Note: Different roles may be filled by the same person on a standards development project. For example, the Standards Custodian may be the Standards Developer, and the Standards Developer may be the Subject-matter Expert. All three roles could be filled by one person. 

[TOC]

4.      STRATEGIES FOR DEVELOPING STANDARDS

Standards are developed only where the use of a standard is deemed to be useful and where it is anticipated that the standard will be reused.

The IMB does not have the resources to develop all the required standards. One strategy adopted is to contract out the role of Standards Developer. In addition, examples of existing high quality deliverables are being gathered and may be referred to in the absence of a standard.

To ensure the effectiveness of standards, the systems branch pilots standards during relevant projects. 

Standards are developed as part of systems development projects to leverage the benefit from the effort already underway and the knowledge gained.

[TOC]

5.      PUBLISHING OF STANDARDS

All standards documents will be published on the Internet unless they contain information which may pose a security threat. Standards documents of this nature will be published on the Intranet only.

[TOC]

6.      METHODOLOGIES FOR DEVELOPING AND MAINTAINING STANDARDS

Standards development and maintenance projects can be classified in the following ways:

Standards projects which can be classified as either 1 or 2 above should follow the methodology outlined in Section 7. Standards projects which can be classified as 3 or 4 above should follow the methodology outlined in Section 8.

[TOC]

7.      METHODOLOGY A

This is the recommended process for developing a standard for a mature technology or methodology, or for preparing a major update to an existing standard. Not all steps in the process are mandatory; mandatory steps are italicized.

Standards are currently maintained in HTML format. 

Once the Standards Custodian has determined what standards are required, and has established a standard development project, the following is the recommended process for the initial development of a standard or for a major update of a standard:

[TOC]

8.      METHODOLOGY B

The process described here is to be used for minor updates and corrections to a standard, or for developing standards for emerging technologies where frequent updates are anticipated.

Minor updates and corrections to standards can be made by the Standards Developer with the approval of the Standards Custodian. No formal signoff is required.

Frequent updates can be made by the Standards Developer working with the Subject-matter Expert to ensure that the standard is sound. Approval from the Standards Custodian is required. Quality Assurance and formal signoff will be completed once the standard has reached a reasonable level of stability.

In each of these instances the changes made must be dated and accompanied by the author's name.

Proper version control of documents must be maintained. Version control guidelines will be determined by a separate project: the Electronic Document Management Strategy.

[TOC]

9. SIGNOFF OF STANDARD

With the exception of minor updates and corrections, standards are considered to be in draft format until signoff has occurred. All electronic versions of the standard must indicate that the standard is in draft format.

Signoff of each set of standards will be done by the Standards Custodian, the Subject-matter Expert, the Standards Coordinator and the Application Development and Data Administration Manager.

[TOC]

10. STANDARDS TEMPLATE

The attached Standards Template should be used for creating new standards. This section provides general information on using the template. Comments relating to specific sections of the template are embedded in the template itself.

10.1 Document Structure

The Standards Template has some mandatory sections (Version Control, Introduction, Conclusion), but most of the content is free-form, consisting of one or more chapters and optional appendices.

Standards should proceed from high-level general statements to detailed descriptions and qualifications. This applies to the document as a whole and to individual chapters, and sections.

The logical decomposition of a standard determines its organization. There is usually some implicit structure in the content that will suggest a structure for the document. For example, here is the table of contents for the Vendor Testing standard:

1. INTRODUCTION

2. VENDOR TESTING
2.1 Unit Testing
2.2 System Testing
2.3 Integration Testing
2.4 Load Testing
2.5 Confidence Level

3. VENDOR SITE USER TEST

4. CONCLUSION

This standard is organized around the idea of type. Each type of vendor testing is assigned a section in the main chapter. The content that doesn't fit into this schema is inserted where it seems to make sense. The topic of Confidence Level is an element of all four types of testing, so it is integrated into the chapter. The topic of Vendor Site User Test, on the other hand, gets its own chapter because involves a distinct way of looking at the subject matter. It discusses stages of testing rather than types of testing. This is partly a matter of judgement. Confidence Level could have formed a separate chapter (especially if it required a long description). Vendor Site User Test could have been an appendix.

Here is an example of a standard organized around two, complementary schemas:

1. INTRODUCTION

2. THE QUALITY ASSURANCE TEAM
2.1 General
2.2 Applications Architect (AA)
2.3 Application Manager (AM)
2.4 Business Analyst (BA)
2.5 Business Expert
2.6 Data Administration (DA)
2.7 Database Administrator (DBA)
2.8 End Users
2.9 Ministry Project Manager (PM)
2.10 Vendor

3. SYSTEM DEVELOPMENT LIFE-CYCLE OVERVIEW

4. QA OF SYSTEM DEVELOPMENT LIFE-CYCLE DELIVERABLES
4.1 QA of Planning Phase Deliverables
4.2 QA of Definition Phase Deliverables
4.3 QA of Analysis Phase Deliverables
4.4 QA of Design Phase Deliverables
4.5 QA of Build Phase Deliverables
4.6 QA of Implementation Phase Deliverables
4.7 QA of Warehouse Phase Deliverables
4.8 QA of Deliverables During Maintenance

5. CONCLUSION

APPENDICES
A. Detailed QA Matrix
B. Bibliography

In this standard the main chapters are organized around roles (Chapter 2) and phases (Chapter 4). Chapter 3 describes the concepts that organize Chapter 4. Logically, it could have formed the first section of Chapter 4, but the flow of the document is clear either way.

Appendices should contain material that is relevant to the standard but would interrupt the flow of the document.

The optimal writing style for a standard depends on how the target audience is expected to use it. A linear style is appropriate for material that is intended for continuous reading. It is typically used for introductory material (at the document, chapter, or section level) and explanations or descriptions that require close attention by the reader. For most of the content in a typical standard a scannable style is appropriate. Except for reviewers, almost no one reads this material from beginning to end. Users scan the text to get an overview and to search for keywords that identify relevant detailed information. While some standards may written entirely in a linear or scannable style, most will use a mixture of both.

10.2.1 Linear Style

A linear style is a form of structured natural language. It favours complete sentences and makes careful use of connective language to signpost links in the writer's train of thought (e.g., "In order to..." "Since..." "As a result of..."). A linear style may include bulleted and numbered lists, tables, and diagrams, but these are always secondary elements. The writer's main points are expressed in continuous, readable prose.

A linear style can be written in either an objective or a casual manner. An objective linear style is clear, concise, and impersonal. It strives to use language in a precise manner, employing appropriate terminology and avoiding vague or ambiguous word, especially unqualified adjectives and adverbs (e.g., "large", "highly", "very").

A casual linear style adopts a conversational tone, may employ colourful metaphors or turns of phrase, and may inject unsupported opinions and evaluations into the text. It is less concerned with logical linkages, expecting readers to draw the connections between sequential ideas.

For writing a standard, an objective linear style is almost always the appropriate choice. Occasionally, a casual style may be appropriate for a short aside. For example, a writer might want to illustrate an idea with a metaphor or summarize a difficult passage in layman's language. Such passages should always be a support for objectively written material, not a substitute.

10.2.2 Scannable Style

The basic principle of a writing in a scannable style is to break the content into minimal units and then to tag them with key words and phrases. In comparison to a linear style, a scannable style relies more heavily on techniques like bulleted and numbered lists, tables and diagrams. In fact, these elements may contain most of the content in scannable sections. The surrounding text may serve mostly to label the content or provide notes on specific points. Paragraphs are kept short and often begin with a summarizing key word or phrase.

A scannable style makes full use of headings and subheadings. Higher-level headings may be short (1-3 word) topics, but lower-level headings are typically full phrases that summarizen the content. Scanning the headings of a section should give the reader a meaningful overview. For example, while something as abstract as "Procedure" might be a good high-level heading, a heading like "Format Checking" sounds too vague for a low-level heading. "Check the format of the user's input file" might be preferable.

10.3 Writing Guidelines

The following is a list of general technical-writing guidelines that apply to writing standards.

• Short paragraphs. Write short paragraphs dealing with a single topic.
• Topic sentence first. Define the topic of a paragraph in the first sentence.
• Short sentences. Write short, direct sentences, averaging 12 words or less.
• Examples. Illustrate key points with appropriate examples.
• Limit detail. Especially when writing in a linear style, omit unnecessary detail or refer to it in a cross-reference.
• Lists. Use bulleted and numbered lists freely, but don't overuse point form where full sentences are appropriate.
• Active voice. Although the passive voice (e.g., "the application was developed by the team") is acceptable in technical prose, favour the active voice ("the team developed the application) whenever both constructions fit.
• Priority. Use the traditional language to indicate the priority (mandatory, recommended, or optional) of each standard.
  • "Shall" or "must" indicate mandatory standards, but "must" is more emphatic.
  • "Should" indicates a recommended standard
  • "May" indicates an optional standard
  • "Will" may indicate a mandatory standard, but is usually reserved for factual statements that are not standards.
• Abbreviations. Limit the use of acronyms and other abbreviations.
  • Freely use any that are completely familiar to the primary and secondary audiences.
  • Spell out unfamiliar ones on their first occurrence in a text - more often if readers are likely to overlook the first occurrence (e.g., in scannable material).
  • Consider compiling a glossary for document with many abbreviations.
  • Use abbreviations freely as a space-saver in tables.

   

10.4 Standards Checklist

The following is an informal author's checklist for reviewing a draft standard before submitting it for review:

• Complete. Does it provide the whole story, or is something missing?
• Correct. Does it reflect the views of subject-matter experts and management?
• Consistent. Does it reflect a single viewpoint? Does it contradict itself or conflict with other standards?
• Feasible. Can it be implemented with reasonable effort?
• Necessary. Are all the elements necessary? Do they add value to the processes the standard applies to?
• Prioritized. Is the standard at the right priority? Are each of its elements? Are "shall", "must", "should", "may", and "will" correctly used?
• Unambiguous. Is the meaning of each element clear?
• Verifiable. How can the Ministry check that the standard has been met?

 [TOC]