SeMI style guide and our voice

Voice and Tone

First of all: keep it brief - we are all short of time - try to minimize your words so they are brief and still clear. It takes a little time but it is worth it.

Blaise Pascale probably said it first (in 1657):

I have made this longer than usual because I have not had time to make it shorter.

There are a lot of style guides in the world and if you have ever done some writing you have probably used them. If you are an experienced writer you don’t need the majority of the advice, if you are new it is pretty handy. Here are some well-constructed guides

If you are an experienced writer you don’t need the guide, you need the more technical part and the glossary for standardization.

Best practices for SeMI documents

Whatever your level of writing skill keep these things in mind:

  • Excellent: we do our best
  • Concise: we don’t waste the reader’s time
  • Clear: we don’t hide behind long polysyllabic words and flowery language
  • Active: we use phrases like “load the file” and do not use “the file should be loaded”
  • Consistent: we use the same voice and elements to build trust and ease reading
  • Dynamic: our writing flows and is not dull
  • Progressive: everything can be improved, there is always a next version that is better
  • Diverse: inclusive, global, thoughtful, considerate

These points represent us – we use them in our writing to show the personality of SeMI

Voices

We have 2 voices which are named after their audience

  • Voice 1: Contributor Programmers and other technical people
  • Voice 2: User Business people, probably non-technical

Our ideal is that no technical language gets into the User documents. If it does you will need to explain the technical terms.

Nuts and bolts: practical details for each document

Format of document sections

Title: All Initial Capitals

Headings: Initial capital only

All documents have the same set of potential building blocks. Some are mandatory. You don't always have to use the name of the section - sometimes it is more useful to use a different or more descriptive word. The full list is

TitleWhat is this aboutMandatoryMD head
AuthorWho wrote ityy
AudienceWho is it foryn
IntroductionShort description of contentsnn
Purposevery brief description of what this doc is foryn
BodyThe main documentyn
ConclusionSum up what has been saidnn
ReferenesIf you have referred to a lot of other documents rather than used in-line linksnn
Date first publishedmetdadata in ddmonyyyyyy
Last updatedmetdadata in ddmonyyyyyy

Note: in Markdown documents (in the GitHub source) some of these items will be automatically generated