Style Guide

Writing style

The writing style for site content should be appropriate to the type of content, so may not be consistent throughout the site. Some reference articles may need a more formal, neutral-observer, academic style, with no use of ‘you’ and limited or no contractions (e.g. shouldn’t). Guides and less formal articles may communicate more effectively through a more informal style, where guidance is given in a personal manner, such as ‘At this point you may want to consider…’.

In all cases avoid the personal pronoun ‘I’ except when quoting directly. ‘We’ can be used, but only to refer to the Writing Systems Technology (WSTech) team as a collective author (We recommend that…).

When providing guidance regarding best practice try to provide some indication of whether it is subjective opinion or objective fact. Recommendations should generally be in bold, and fall into four loose types:

Developers may choose to - There is no single good option, and developers should consider various alternatives.
We recommend that - There seems to be one option that is best for most developers, that we ourselves have chosen and that we suggest that others follow.
Ascender and descender values should - There is clearly a best option and to do otherwise would be asking for problems.
Production glyph names must or Font names need to - if you don’t do this then your font is unlikely to work properly.

Language, spelling, punctuation, and dates

Content should mainly be in English, however, that is not a rule, and content in other languages is welcome. If there is a need for multiple versions of a page in different languages we may wish to install extensions that make it easier to author and navigate between content languages.

English spelling may be American, International, or British to reflect the diversity and personal style of team members. It should, however, remain consistent throughout a page or pages of interrelated content. British text should use Oxford spelling, with the -ize ending for words such as organize, realize, and privatize, but with words ending in -yse retaining the s, as in analyse and catalyse etc.

Punctuation should follow general guidelines:

Quotations can use either single (British) or double (American) quotes as long as they are consistent throughout a page, although single quotes are slightly preferred. Place punctuation marks outside of quotation marks unless the punctuation is part of the quotation itself. This practice is sometimes referred to as ‘logical punctuation’. Source files can use either straight or ‘curly’ quotes—rendered pages will convert them to typographic ones.
Comma-separated lists should use the ‘Oxford comma’ to provide clarity, as in: The design process involves initiating, experimenting, forming, harmonizing, and adapting. This can be applied flexibly.
Ampersands should only be used when they are part of a name or title or heading, such as Scripts & Languages.
The copyright symbol © should be used rather than (c) except in quotations or examples.
Abbreviations should include full stops: e.g., i.e., etc., vs.

Dates should generally be formatted as yyyy-mm-dd (e.g. 2025-02-27) to avoid confusion. Use specific dates where known. Avoid terms that assume the present time, such as ‘ten years ago’ or ‘currently’.

Capitalization

Page titles should use English title case, in which first, last, and any major words are capitalized, but not minor words (conjunctions, prepositions, articles).

All other headings should use sentence case, in which only the first word is capitalized except for names and proper nouns.

AI use

Although in some cases it may be difficult to avoid encountering AI-generated content when researching and authoring content for this site, it may only be used for reference purposes and never to directly prepare text or image content. All content must be authored and edited by one of the site’s authors. Use of AI should also reflect SIL’s AI Ethics Statement.

Referencing

(to be added later based on further discussion)

Figures & illustrations

Original or SIL-owned figures, illustrations, and images do not require captions or figure numbers if the in-text reference to it is close to the image and the reference is obvious. Figure numbering can be used if helpful, although it can make later page maintenance more difficult. Numbering should start at ‘1’ on each page and not be carried over to other pages, even if the content is related. There is no existing or planned system for automated figure numbering.

If the image is not original, the source of the image and by what permission it can be used must be included in a caption or in the text. Captions do not have any special handling but can be used - see Images. Captions can contain any kind of information, including links, and do not require use of figure numbering.

Guidance on filenames, file locations, frontmatter, and tags is now in File Location and Frontmatter Reference.

Guidance on using Markdown has been moved to Markdown Reference.