The documentation, website, and competencies all follow the guidelines outlined in this document. This guide is for anybody who wants to make changes to these resources that other people will have to read later.
These guidelines apply to communications by the Engineering Progression Working Group, documentation in this repository and website, and the written levels and competencies.
- Use contractions: "we're" over "we are"
- Starting sentences with conjunctions like "but" or "so" is allowed
Communication should be conversational. We speak with contractions and begin our sentences with conjunctions, so we would like to translate that to our writing as well. If it sounds like something we'd say out loud, we're likely on the right track.
- do: "We would recommend you do ..."
- don't: "I would recommend you do ..."
The work we do is as a team, and we rely on each other and the input from our users to be able to maintain and deliver our work. The use of "we" can extend to include the reader, and discourages the use of the passive voice.
- do: "We recommend you do ..."
- don't: "It is recommended you do ..."
The active voice provides clarity, context and responsibility. If we are passive in our writing, we become vague and we distance ourselves from what we are trying to convey. This isn't helpful to our users, who rely on and trust our ability to take responsibility for the work we do.
Shorter sentences are easier for readers to take in. Longer sentences or lots of commas can often be broken down.
By that, we mean qualifiers. Qualifiers are words like "pretty", "mostly", "probably", "usually". They can make the information in our writing ambiguous and are often read as an opinion rather than a fact. Though we want to be conversational, we don't want to start documenting unhelpful statements.
- code variables go in
back-ticks - use tables
- use asides
- use lists
- highlight copy where appropriate
- use informative and short headings
By providing any of the above, we'll allow skim readers to quickly scan our documentation to find relevant information. It also helps us break different topics down into digestible sections.
- do: "This site contains everything you need to know about Owls"
- don't: "This site is a one stop shop for Owl facts"
We work with people for whom English (or British English) aren't a first language. We need to keep in mind that there is phrasing that non-native English speakers may not be familiar with.
- do: "Run the following command ..."
- don't: "Simply run the following command ..."
Words like "obviously", "simply", "basically", "just", "clearly", "all you need to do" are the types of language we try to avoid. We shouldn't assume that something that is clear to us will be clear to whoever is reading; we don't set benchmarks for what people know in our technical writing. The above words are also filler words that lengthen a sentence without improving its content.
- do: "It would be a wild thought..."
- don't: "It would be crazy to think..."
Ableism is a form of discrimination against people with physical, mental or developmental disabilities. In language, it presents itself as wording like "lame", "crazy", "blind", "dumb", among some others. This wording can be insulting to those that do have a disability, and it is entirely possible to use different vocabulary to convey our point.
These guidelines apply to writing engineering competencies, and expand on the general guidelines above.
- Competency summaries must start with a capital letter
- Competency summaries must not end with a full stop
When an engineer discusses their career progression with their manager, they should be able to agree whether a competency is fulfilled. It is important that each competency is demonstrable:
- bad: "Can write tests"
- good: "Writes tests"
Sometimes a competency needs a frequency qualifier so people know if they should always be doing something or if they need to have demonstrated they’ve done it once. Some examples used in the existing competencies:
- Regularly
- Often
- Usually
If the competency summary has an "and" in it, it might be saying too much. Consider whether you're combining two competencies into one.
We use examples in competencies where they will clear up ambiguity in the summary. They are also used to explain how a general competency might apply to people in different domains.
Where possible, state examples in the positive, not the negative:
- bad: "Creates an inclusive environment by not interrupting people"
- good: "Creates an inclusive environment by making sure everyone in meeting gets to contribute"