Origami is designed to serve users from a number of different backgrounds, working with a variety of different projects. As all people come with different experiences and types of understanding, we try to consider all of our communication very carefully.
To strike a balance between a professional and friendly tone, while being clear and helpful, our writing follows a few essential writing styles and uses of language.
As we’ve said, we aim to 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.
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. It is language that can extend to include the reader, and discourages the use of the passive voice.
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. If we find we’ve ended up with too many commas or a long running sentence, odds are we can break it down into more readable chunks.
By that, we mean qualifiers. Qualifiers are words like “pretty”, “mostly”, “probably”, “usually”. They can make the information in our writing ambiguous. They can also communicate an opinion about something. Though we want to be conversational, we don’t want to start documenting unhelpful statements.
back-ticksBy 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.
We work with many different nationalities and levels of command of the English language. We need to keep in mind that there is phrasing that non-native English speakers may not be familiar with.
In addition to general writing styles, grammar and spelling, there are a few customised styles that we use specifically for Origami.
At the FT, most people are familiar with the Origami team. But outside of the company, origami is something entirely different, and it is important that we make that distinction.
Our components are named in lower case and are available to use from package managers in the same way. We reserve capitalisation for component code, when we need to write syntax and need to conform to syntax convention.
Similarly to capitalising “Origami”, we capitalise the services we maintain because they are distinguished products that have user-facing interfaces of their own.
The Origami team is based in London, UK. We speak British English and we work for a British newspaper, so we like to keep our documentation aligned with both of these things. Having said that, we use American English in our code and component/service names, because we aim to be consistent with the way most programming languages are written.
Now that we have covered sentence structures, we also need to approach word choices. We are part of a company that strives to be diverse and inclusive, and we aim to do the same in all aspects of our work, including our documentation.
Words like “obviously”, “simply”, “basically”, “just”, “clearly”, “all you need to do” are the types of language we try to avoid. Our documentation aims to explain our products to a number of people we don’t know, so we shouldn’t assume that something that is clear to us will be clear to whoever is reading. They are also filler words that lengthen a sentence without improving its content.
We don’t set benchmarks for what people know. We are here to help everyone use the components and services we put effort and care into. We want to make our work accessible to all, regardless of what their knowledge scope is.
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 guides are here to help us along when we have doubts about what we’re writing, but as long as we’re writing with other people in mind, we’ll be on the right path. If you have any questions, please get in touch with us via Slack or Email.