Grammar style guide

Clause9 offers a wealth of features, both in the user interface and in its clause grammar. This can lead to situations where members of the same team would choose a different road to Rome, leading to confusion and potential errors.

This style guide offers an overview of the rules of thumb that the Clause9 team aims to apply in the clauses it writes, to foster uniformity across the members of its team. They are based on common experience, and should be seen as best practices for the entire Clause9 community.

As always, a rule of thumb or best practice is not set in stone — there are good reasons why you sometimes need to deviate from them.

Using codes instead of text fragments

As explained elsewhere, you should use short codes for predefined datafield values and predefined Q&A answers, instead of text fragments that can be inserted as such in a document.

The code should be in lowercase.

The code should be immediately perceived as a code, instead of a text fragment, so nobody would be tempted to use the code as such in the document text.

The code should use hyphens instead of spaces to combine different words or word parts. For example, use fixed-location instead of fixed location.

The code should be a balance between conciseness (= less typing every time you use the code) and readability (= less mental overhead in figuring out what the code means”). For example, when finding a good code for variable price per unit, vppu is concise but difficult to understand for somebody reading your clause, while variable-price-per-unit is quite a lot to type; instead, var-unit-price is probably a good mix.

When choosing a code for a country, you should use a two-letter standard country code, in small letters. (The small letters avoid that somebody would be tempted to use the code as a text fragment — using “BE”, “UK” or “US” is quite common in contracts, while using “be”, “uk” or “us” would be weird or even downright confusing).

In a multi-lingual context, you should use English for the code, not only because this will be easier for foreign colleagues, but also because English is guaranteed to be available in every version of Clause9.

• You can deviate from this rule if either the likelihood that your clause will ever get translated into English is very small. However, do not forget that Clause9 promotes the reusability of clauses, so you may not always be able to anticipate where your clause would end up being used.