|
Web Document Style Standards
|
Version 2.14
Edition 1
|
Document ID:
|
WDSS
|
|
Author:
|
Jaycee Phua
|
|
Reviewed by:
|
Danny Goulas
Daniel Woodhouse
Matthew Sykes
|
|
Last Update:
|
3 September 1999
|
Revision History
|
Date
|
Modifications
|
Reason
|
Version
|
|
1999.03.21
|
Entire contents adjusted (JP)
|
Adapted from es204-dsstd-1.0 document
|
0.1d
|
|
1999.03.23
|
Document contents formatted (JP)
|
Conformance to Style Specification
|
0.4d
|
|
1999.03.24
|
Reviewer added to Cover Page (DG)
|
Technical Writer** check
|
0.7
|
|
1999.03.24
|
Various sections reworded (JP)
|
PG Reviewer suggestions (DG)
|
0.71
|
|
1999.03.26
|
Reviewer added to Cover Page (MS)
|
Quality Assurance check
|
0.8
|
|
1999.03.27
|
Various sections reworded (JP)
|
QA Reviewer's suggestions (MS)
|
0.81
|
|
1999.03.28
|
Word Processor Template implemented and utilised (JP)
|
Follow document specs
|
0.9
|
|
1999.03.29
|
Content finalised (JP)
|
Preparation for 1st draft submission date
|
1.0
|
|
1999.03.30
|
Documentation adapted to HTML
|
Formatted for appropriate online submission
|
1.5d
|
|
1999.03.31
|
Addendum added outlining Web-adaptations (JP)
|
Explain Word Processor-Web adaptation
|
1.8d
|
|
1999.04.12
|
Entire contents revised (JP)
|
Complete document Web-adapted
|
2.0d
|
|
1999.04.29
|
Sentence-Spacing added to Text Specifics Section; spacing adjusted
|
Rule addition to DSS
|
2.01d
|
|
1999.04.31
|
Sections reorganised (JP)
|
Increase readability
|
2.1d
|
|
1999.05.03
|
Reviewer Added to cover page -- MS, content revised (JP)
|
QA Reviewer's suggestions (MS)
|
2.1
|
|
1999.05.14
|
Style mistake corrected
|
Conformance to (latest) Style Standards
|
2.11
|
|
1999.05.14
|
Table of Contents (TOC) & TOC section revised.
|
Assessor's suggestion (Raj)
|
2.12
|
|
1999.08.19
|
Revised content relating to format/appearance of documents (JP)
|
Style Standards revised to reflect new Web Page Style
|
2.13
|
|
1999.09.03
|
Cover page style changed (JP)
|
Conformance to style standards
|
2.14
|
** As of July 1999, all Technical Writers have formally been combined with Web Engineers to form
the Publishing Group.
Table Of Contents
1. Scope
This document (Edition 1) outlines the style standards that are to be
followed concerning all Team Synergy projects. All documents
created for official use with any Team Synergy related project
must strictly adhere to this document specification, unless a newer edition
of the Web Document Style Standards has been appropriately
authorised.
Any sections of this document not understood by any persons affiliated with
Team Synergy should approach the appropriate Web Style Standards
Coordinator, for further clarification (through appropriate channels).
It is imperative to point out that this documentation makes frequent reference
to the Document Content Template, described in greater
detail in [Section 4.1]
|
Note:
|
The main content of this document is intended as a specification for
Web-related (HTML) use only. For a Word Processor-adaptation to this
Web Document Style Standards, please consult the
Style Standards Coordinator.
|
2. Versions
Each document created (or revised) shall always be allocated a version number,
indicating level of completion for that document.
The version number is proportional to the level of completion for that document.
A document that is in its first final form is labelled version 1.0. Any document
in its draft state should be signified by a "d" following the version number:
When minor updates are made, the second value following the decimal place should be
incremented by one. For major updates, the first value following the decimal place
should likewise be incremented by one. For new versions, the number preceeding the
decimal place should be incremented by one, and the values following the decimal place
should be reset to zero.
The latest version number for the document should be displayed at the top of
each document in the Title Area [See Section 10].
3. File Formats
Any documentation written by members of Team Synergy, for use in official project
documentation should be text based, with clear emphasis on Heading Titles, and
other aspects of the text that should be distinguished. However, the
preferred method is HTML format. Submitting
documents/files in this format shall improve processing time.
Any necessary graphical images
requiring processing should be in GIF or JPEG format. Choice on the format is left to the
discretion of the writer; however it is standard Team Synergy practice to select the image with the
smaller file size.
| Note:
|
Selecting
the more appropriate image format (and consequently the more compact file
size) depends on the complexity and required quality of the final image.
|
Those Team Synergy
members who require assistance in optimally compiling their documents or images
should consult a Publishing Group Member.
4. Page Setup
All official documentation relating to any Team Synergy project should be processed in a
format suited for viewing on the World Wide Web.
The Web Browser used to display the document should
automatically handle all page setup details. Consequently it would be
irrelevant to cover specific page setup requirements for Team Synergy
documentation.
Additionally,
since the Web Browser itself automatically interprets and decides the method to
which an Web document is displayed, all content is adapted to suit the 'current'
viewing context of the document. For example:
- Video resolution
- Colours used
- Web browser in use
Word-wrapping is one inherent feature that assists in
accomplishing this feature.
| Note:
|
The only
requirement that should apply to documents based on this edition of the Web Document Style
Standards is that the background is set to White. Ensure that this requirement is conveyed
to the Publishing Group member responsible for posting
the document to the World Wide Web. |
Page Setup details specific to Word Processors can be
referenced from the original Document Style Standards (for Word Processors).
4.1 Templates
In order to minimise the delay when attempting to
strictly adhere to the many standards that must be followed for an official Team Synergy document, the styles and settings
defined in this document has been made available for remote download via the
World Wide Web in an text file consisting of HTML code.
The template consists of samples
of formatting styles and is ordered such that it can be used as a starting point
for upcoming Team Synergy documents, or as a
reference to the procedures and formatting expected of documents containing HTML
Source.
The Document Content Template
can be obtained from here.
5. Style of
Documentation
Each Team Synergy
document should conform to the following requirements stated in this
section. Any queries regarding the application of these requirements
should be brought to a Publishing Group Member through appropriate channels.
5.1 Numbering System
A numbering system is necessary in aiding navigation
throughout a document, such that if a section or table/diagram is referenced
from another part of the document, a reader can easily find the topic according
to the numbering allocated to that section or page. It is also mandatory
to include a Table of Contents [See Section 8].
Where numbering is concerned,
decimal numbers (ie. 1, 2, 3, 4... ) should be used throughout any
official Team Synergy project
documentation. Other numbering methods including Roman numbering
(ie. I, II, III, IV... ) or Alphabetic numbering (ie. A, B, C, D...
) should not be applied. Bullets can be applied in place of numbers, but
only where suitable [See Section 7].
| Note:
|
The only
exception to numbering methods in use are for Appendices [See Section 11],
which require numbering in Alphabetic form.
|
Numbering is mandatory for headings, table and figure
captions. Such objects should be numbered with respect to its location
within the document, to assist the reader in identifying its relevence to a
specific section.
Multiple levels of numbering can be applied if more than
one topic is covered to a section (ie. if the depth of the section
consists of more than one sub-topic).
The formatting contained within this document should be
used as a prime example of what is expected when numbering is concerned.
5.2 Text Style
To ensure complete adhesion to the Team Synergy Document Style
Standard, the main assumption made for the creation and viewing of Team Synergy Documentation is that it should be
performed on an Operating System that utilises typefaces based on the TrueType font-set. For cases where TrueType fonts
are unavailable, the required typefaces for Team Synergy documentation can be substituted with
equivalent alternatives.
The
following table is a list of fonts used in Team Synergy documentation under a TrueType
font-enabled Operating System, including the acceptable substitutes that may be
used to display and/or output the documentation correctly.
| Font
|
Font Type
|
Font
Substitutes |
| Arial |
San Serif |
Helvetica, San Serif |
| Courier New |
Monospaced |
Courier, Terminal |
| Tahoma |
San Serif |
Arial, Helvetica, San Serif
| Table 5.2 - 1: Fonts and
Font Substitutes used in Team Synergy
documentation.
It can be assumed that for all other cases, the Arial font (coloured black) should be used. The
default (Web Browser) size for text should be 2 (relative to the HTML font
scaling system), as in the following example:
| eg.
|
| HTML: |
<font face="Arial" size="2"
color="black"> | |
| Note:
|
Using the
RGB Hexadecimal Code Index, Black is
"#000000". |
5.2.1 Heading Font
Styles
The following table outlines applications within a
document where a specific font is used. For cases not specified in the
following table, one should consult the Style Standards
Coordinator.
| Text Style
|
Font
|
Size
|
Font Style
|
Alignment
|
Example
|
| Document Title |
Tahoma |
6
|
Bold |
Left |
|
| Document Version |
Tahoma |
4
|
Bold |
Center |
Version X.Xd |
| Document Edition |
Arial |
2
|
Regular |
Center |
Edition X
|
| Heading Level 1 |
Arial |
5
|
Regular |
Left |
X. Heading 1 |
| Heading Level 2 |
Arial |
4
|
Bold, Italic |
Left |
X.X Heading 2 |
| Heading Level 3 |
Arial |
3
|
Bold |
Left |
X.X.X Heading 3
|
| Heading Level 4 |
Arial |
3
|
Underline |
Left |
Heading 4
| Table 5.2.1 - 1: Heading
Styles and expected format
Note that there are specific Non-Breaking Space requirements for Level 1 to 3
Headings. Refer to the Non-Breaking Spaces area in Section 5.2.3.
5.2.2 Normal Text Font
Styles
In special circumstances, certain methods of emphasis
are required. The following table outlines the situations where different
font styles may apply:
| Application |
Font
|
Font Style
|
Example
|
| Normal Emphasis |
[Default] |
Italic |
emphasis |
| Heavy Emphasis |
[Default] |
Underline |
emphasis |
| Team Name |
[Default] |
Bold |
Team Synergy
|
| Document Referral |
[Default] |
Bold, Italic |
Document Title |
| Example Text |
[Default] |
Italic |
|
| Note Box Text |
[Default] |
Regular |
|
| Caution Box Text |
[Default] |
Regular |
|
| Computer Text (Output) |
Courier |
Bold |
|
| Language Source (Code) |
Courier |
(Green) |
| Java: |
system.out.println();
| |
| HTML Source (Code) |
Courier |
(Blue) |
| Table 5.2.2 - 1: Formatting requirements for Normal
text.
Emphasis can be used in cases where new ideas or objects
are being described, by Italicising the text.
When specific words are
significant, "Heavy Emphasis" (as opposed to "Normal Emphasis") should be applied by Underlining (ie. must, not, etc. ).
However, emphasis should be used sparingly; the required emphasis should be
achieved by rewording the sentence.
Text designed to describe an idea can be pointed out by
using "Example Text". Example Text should always be italicised. If text within Examples
require emphasis, italics should be inverted (ie. 'Normal' Example Text is
Italicised, and 'Emphasised' Example Text is regular). Normal Emphasis and Heavy
Emphasis can also be applied in Example Text (where necessary).
If emphasis of significant portions of text is
necessary, a "Note Box" can be introduced.
| eg.
|
| Note: |
This entire portion of text could be of
significance to the reader; not just a single word.
Emphasising text within examples would appear like this, or this.
|
|
Alternatively, a similar principle to the Note Box can be utilised by using a "Caution Box":
| eg.
|
| Caution: |
This box should be used only rarely, and
obviously only when a portion of text requires the reader's utmost
attention. |
|
Labelling schemes (ie. "Java" or "HTML") for
computer-related sections are only necessary when occasional references to the
coding language are made throughout a document. If a specific language is
constantly referenced throughout a document, labelling can be ignored, as long
as the coding language being discussed has been outlined in the Document Scope.
This should also mention how the coding language can be distinguished from
normal document text (ie. it is monospaced, and is a certain colour).
5.2.3 Text Specifics
Non-Breaking Spaces
If the writer or reviewer finds that a collection of
words must remain together no matter what, one can use a Non-Breaking Space in place of a Conventional Space. Use of Non-Breaking Spaces
may arise when the wrapping of words to the next line are to be prevented.
It is up to the document writer to
decide whether it is necessary to utilise this spacing method. In most
cases, however, it is plainly obvious when Non-Breaking Spaces should be
implemented.
Specific
instances where Non-Breaking Spaces should be implemented in Team Synergy documentation include:
- Inside Section Reference Brackets ("[", "]")
- Team Name usage
- Headings (Level 1 - 3)
- Spacing between Sentences [See below]
It must
be said once again, that to best understand the context of these requirements,
the reader should refer to the actual HTML code which forms this and other Team Synergy documents.
| eg.
|
| HTML: |
- [Section X.X]
- Team Synergy
- X.  Heading Level 1
X.X Heading Level 2
X.X.X Heading Level 3
| |
Spacing between Sections
Paragraph text should be separated with a line; starting
each paragraph with indents are neither condoned nor are they necessary in
'modern times'. Readers should take this document as an example of what is
expected for paragraph style and the HTML code of which it is composed of, to
understand the requirements of the Web Document Style Standards.
So long as the Document Content Template
is correctly and sensibly utilised, the writer compiling the document in HTML
format will not require learning the specifics of when spacing between sections
is necessary and unnecessary. For an in-depth run-down of the HTML details
mentioned here, refer to [Appendix A].
Spacing between Sentences
All sentences within paragraph sections should be
separated by two spaces. This ensures that each sentence can easily be
distinguished from another, preventing reading/viewing difficulties.
| Note:
|
When
collating a document with HTML, extra spacing included by the writer
appears to be ignored. To overcome this, make use of Non-breaking Spaces (described above) as follows:
| HTML: |
Previous Sentence. Current Sentence.
| |
Page Breaks
Page Breaks are necessary if a section of the document
requires differentiation from another unrelated section.
It is helpful to note, however,
that Page Breaks (in the case of Web documents) do not have the same 'literal'
meaning as when applied in Word Processors.
Page Breaks in terms of Web documentation consist
essentially of a Horizontal Line, to separate unrelated sections of Team Synergy documentation.
Hyphenation
Hyphenation is the process whereby a word is split and
hyphenated between two lines in order to maintain even spacing within paragraph
text. It can often be found used in conjunction with Justified text alignment, in printed media (such as
Newspapers) that require visible distinctions between columns of text.
Since Team Synergy documentation should be implemented
using HTML, Hyphenation is not only unnecessary, it should not even apply when
dealing with Web-based content.
5.3 Table Style
[Table 5.3 - 1] (below) outlines the main attributes
that should be observed for all Team Synergy
tables. For those attributes stated in the table, their values are fixed
and should not be altered in any manner.
The sole exception applies to the Table Width attribute. In most cases the Table
Width (with respect to the page margin) should remain at the default setting;
however it may be varied depending on the width requirements of the contents
within a table (as in [Table 5.3 - 1], where its contents do not require much
table width).
Each Table should also be accompanied by
a numbered Caption stating the purpose of the
table. This Caption should appear below the table. If necessary, a
Table Footnote can also be included, which should
appear between the Table and the Table Caption.
For specific HTML Tag details
in creating Tables styled to the Team Synergy
specification, refer to [Appendix A5.3]
| Attribute
|
Setting
|
| Table Alignment |
Center
|
| Table Width |
95% *
|
| Border Colour |
White ¹ |
| Table Border (Width) |
0
|
| Cell Border Width |
0
|
| Cell Spacing ² |
1
|
| Cell Padding ³ |
5
|
* Default
setting
¹ RGB Hexadecimal Index: #FFFFFF
² Spacing between the table's cells
³ Spacing between the contents of cells and the cells
themselves
| Table 5.3 - 1: Table Attributes
As a starting point, to
correctly duplicate the specific appearance of Team Synergy Tables, it would be highly advisable
to utilise the
Table example found in the Document Content Template [See Section 4.1]. However, this
section shall provide a basic description of the specific settings required.
The following table [Table 5.3 -
2] outlines the characteristics of the data displayed within and around tables.
| Table
Style |
Font Size
|
Font Style
|
Alignment
|
Background
Colour ¹ |
Example
|
| Red
|
Green
|
Blue
|
| Table Heading |
2
|
Bold |
Center |
99
|
99
|
99
|
|
| Table Contents |
2
|
[Regular] |
Left |
CC
|
CC
|
CC
|
|
| Table Footnote ² |
1
|
[Regular] |
Left |
CC
|
CC
|
CC
|
|
| Table Caption |
1
|
[Regular] |
Center |
CC
|
CC
|
CC
|
|
¹ RGB
Hexadecimal Code Index (ie. #RRGGBB )
² Optional | Table 5.3 - 2: Table Content Style
The default text colour for all text in tables is black.
5.4 Indentation
The main application for Indentation is to distinguish
the status of a sub-section of text from its main section. Indentation or
sub-sections is not advised as it effectively reduces the amount of workable
content-space in Team Synergy documentation.
If 'distinguishment' is
required, one can utilise the various methods of displaying text as described in
[Section 5.2.2].
Essentially all document content,
including sub-sections, should correspond to the default unindented,
left-aligned page setting. The exception lies with Table of Contents, Bullet and
Numbered-Bullet lists, which require indentation in order to differentiate those
lists with sub-lists.
5.5 Images
Images may be used as required in the document.
Acceptable Image formats are described in [Section 3].
All images should be accompanied
by a Caption consisting of the Image's Number [See Section 5.1], and a description of
the image. The Text Style for a Caption is exactly the same as for Table Captions, however the labeling for
Images should appear as follows, whereas Table Captions require a label titled
"Table X..."
Figure 5.5 - 1: Constraints for the simulated image
Note that the precise dimensions of the image should be
specified with its Tag in the document's HTML Source.
Where images require
'distinguishment' from their surrounding document content, a basic black border
of width 1 (HTML-specific) should be included with the HTML Image Tag, to
signify the bounds of that image.
5.6 Date Notation
Dates should be given in the backward notation
"yyyy.MM.dd" or "yyyy/MM/dd".
| Note:
|
To better
understand what is expected for the date notation specified by Team Synergy, it is helpful to know that
computer dating conventions suggest that "MM" indicates the month be
stated explicitly in two-digit format (03 being March) as opposed to "mm",
which indicates the month be displayed with two digits only where applicable. When "dd" is
specified, the day should be stated explicitly in two-digit format, as
opposed to "d" which indicates the displaying of two digits, also only where applicable.
|
Thus the month and day should be explicitly provided in
two-digit format-- preceding zero included.
Using the backward convention ensures that regions that
follow other conventions (ie. 07/24/2004) have a clear understanding of
the declared date. Use of the backward notation also ensures lists sorted
numerically remain in a logical date-based order.
If required, the date can also be stated in the standard
International form consisting of "dddd d mmmm yyyy", where the worded-day
("dddd") is optional, but spaces must separate each aspect of the worded date
notation. Separating the worded-day and the numbered-day, or separating
the month and year with Commas is optional but not preferred.
| eg.
|
{Monday} 24 July 2004
|
6. Headers and
Footers
It is implausible for Web-based documentation to contain
Headers and Footers, plainly due to the fact that Team Synergy Web based documentation do not
consist of distinct pages. Consequently it is unnecessary for this section to be
covered in any depth within this Web Document Style Standards.
In any case, if Headers and
Footers are required they rightfully belong to the Publishing
Group's Web Style Standards Domain.
7. Bullet
Points
Bullets can be used to define a complex statement in
point format, or identify the composition of components within a statement.
Although not recommended, should
the need arise for multiple-level bullets, the types of each successive level of
bullet lists should be as follows:
All bullet statements should begin with a capitalised
letter, Bullets should not include any method of grammatical linking between
them. However the ending of a statement with a period is acceptable.
| eg.
|
- the first letter of this point's letter is not
capitalised
- The end of this point is incorrect, then
- The end of this point is also incorrect, or
- The end of this point is wrong, and
- The end of this point is also wrong;
- The end of this point is correct.
|
| Note:
|
Numbered
Bullet lists may also be used if required. All other requirements
applying to Bullet Points also apply to Numbered Bullet lists.
|
8. Document
Layout
This section details all the various parts that are
essential to every document (apart from the actual document content):
8.1 Title Area Section
All documents using this standard shall have a cover
page/sheet with the following information:
- Document Title .
- Document Version Number.
- Document Edition Number.
- Document ID: the Identifier of the document is the
abbreviation of the Document Title.
- Author(s) of the Document
- Reviewer(s) of the Document
- Date Last Modified, to be specified in worded-date
notation [See Section 5.6]
8.2 Modification History
This is a compulsory section. This section may be
left empty only if the document has no known modification history. All
modification from the first released version shall be tracked and documented in
this section. Modification may only be made after it has been formally
reviewed and approved.
This
section shall include the following information in a table format:
- Date of modification:
This shall be in the appropriate date format specified in this document [See
Section 5.6].
- Description of the modification(s).
- Reason(s) for the
change.
- The version number of the
newly modified document. On determining a valid version number, refer to
[Section 2].
All
information contained within the table shall follow those formatting settings
specified in [Section 5.3].
8.3 Table of Contents
Each document covering multiple topics should have a Table of Contents. This information should be
included at the start of the document, following the Title Area. The format and style
of the Table of Contents (TOC) should follow the example provided at the
beginning of this documentation.
There should also be a Hyperlink allowing the reader to immediately access the
related content corresponding to the TOC listing. The following table is a
sample of Formatting Style for TOC text.
| Note:
|
The
examples provided in the table show exactly how they would appear,
including the hyperlinking ability; however the links for those examples
serve no real purpose whatsoever-- they are just part of the example.
|
| Text Style
|
Font
|
Size
|
Font Style
|
Alignment
|
Example
|
| TOC Level 1 |
Arial |
3
|
Bold |
Left |
X. TOC
1 |
| TOC Level 2 |
Arial |
3
|
Regular |
Left |
X.X TOC 2
|
| TOC Level 3 |
Arial |
2
|
Regular |
Left |
X.X.X TOC 3
| Table 8 - 1: Table of Content Styles and expected
format
Level 4 Headings should be
excluded from TOC listings purely because they would waste precious listing
space. In terms of document content, Level 4 Headings are also likely to
be too minor to be listed. If a Level 4 Heading should contain important
content worth mentioning within the TOC, it should be 'promoted' to a Level 3
Heading. However, writer discretion is advised when doing so.
8.4 Appendices
Appendices can be used when it is not appropriate to
include information within the main section of the document. A reference
to the Appendix shall be stated explicitly in the main content.
All entries in the Appendix shall
be explicitly included in the Table of Contents [See
Section 9].
8.5 Quoting
There may be a need for direct quoting from reference
sources. When this is to be done it should be started with opening double
quotes "and closed with the same". Each quote shall be referenced [See Section 14] with appropriate sources.
The reference number shall follow the quote in superscript format.
| eg.
|
Mr E. states that he "had me some sex"2
|
8.6 Footnotes
Footnotes shall be used for clarifying information that
is not directly relevant to the current paragraph but still important.
Each footnote shall follow at the end of each document's main content (ie.
before the Appendix). A Page Break [See Section 5.2.3] is necessary in
distinguishing the Footnote section from the rest of the document.
Footnotes are optional but should be avoided where possible.
| eg.
|
| HTML: |
This is some text<sup>1</sup>
| |
would produce:
This is
some text1 |
All Footnotes throughout a document should follow the
same number counter starting from '1'. The Footnote Reference should also
be accompanied by a Hyperlink to the actual Footnote
situated at the end of the document.
Footnotes can also be applied to Tables, but the actual
Footnote should be situated directly after the Table, before the Table Caption.
| Note:
|
Where only
a single Footnote is required, an Asterisk ("*") can be used in place of a numbered Footnote.
|
8.7 References
Each time a quote is listed, the reference source will
be shown. Each first reference to a text will contain:
- Author / Editor: Given Name and Surname
- Reference Title, specified in Italics
- Publisher Name
- Year of Publication
- Page Number
A second reference need only
contain the Author's/Editor's Surname followed by the page number.
8.8 Index
Any document that is more than 30 pages in length shall
provide a detailed index at the end of the document. The content and level
of detail presented in the index is left to the discretion of the author(s) of
the document.
Hyperlinking rules apply to Indexes for all Web-based
documentation, whereby the reader may access the indexed word based only on the section the indexed word is contained
in. Providing greater depth in indexing would require excessive effort on
the document writer's part.
|
