Writing tips for technical professionals

This article contains a selection of tips aimed at technical writers who review, comment or draft technical documentation which can be attached to, or included in, contracts or proposals.

It contains some practical advice and addresses common issues that I have come across over my 15+ years of commercial negotiations and contract writing.

If you are a technical professional or engineer and have ever had to contribute to a technical document or specification it is highly likely that this will get attached to a contract. Therefore understanding some basic information about contract writing can be an advantage.

Contracts

Contracts are all around us, from the terms of service on our favourite app to the rental or purchase contract on our home.

What is a contract?

The dictionary definition of a contract;

A contract is an exchange relationship created by oral or written agreement between two or more persons (parties), containing at least one promise and is recognized in law as enforceable

This definition can be a little confusing but you can think of it more simply;

A contract is an explanation to the outside world (or a judge) of what the two contracting parties have agreed.

Contracts are a tool for both parties to make sure their goals are achieved. Here is a list of common issues that contracts are used to address:

Within the contract are a number of key concepts which are important for technical writers to understand:

Technical documents and attachments
Performance Guarantees
Defect Warranty

Technical Documents

Photo by **Anamul Rezwan** from **Pexels**

Technical documents are effectively incorporated into a contract when attached or referenced. Technical documents commonly clarify the scope of works in the contract and the performance of those works. If these items are not properly described it can quickly lead to cost issues.

Interestingly when examining a complex sales agreement the technical annexes often consist of 10 to 100 times the number of pages of the main contract. This fact is often neglected when the sales teams and lawyers haggle on the contract terms and price.

Unfortunately, this also means that the technical annexes are where the mistakes more commonly arise.

Performance Guarantees

When selling a product or long term maintenance contract the customer will expect some form of performance guarantee or warranty. Where possible performance guarantees should be accompanied by a pre-defined remedy or penalty (liquidated damage) in case of a failure to achieve the guaranteed levels. It is often preferable to have explicit liquidated damage described so that the parties can define the risk exposure in advance, rather than an open-ended remedy.

When writing a performance guarantee it is important to ensure the following:

The guaranteed level is specified (e.g. 90%, 100mph, 20V).
The time of such test is defined (e.g. within 1 year of installation).
The testing proceedure described (e.g. using a multimeter, by measuring the distance between x&y).
The test tolerance or accuracy of the measurement is defined (e.g. +/- 5%).

If any of the above are not specified you are leaving the determination up to someone else in case of a dispute.

Warning: In sales contracts, guarantee and warranty can be considered as similar concepts when describing performance. It is common practice though that performances are guaranteed while defects are covered by a warranty.

Defects Warranty

Defect warranty clauses are found in most sales contracts and if the contract is silent then the warranty is defined by the applicable law. This clause describes what happens in case the goods or services are not performed in accordance with the contract. This is one of the most critical areas to focus on when attempting to control risk in the execution of a deal.

A good defect warranty clause describes the following:

Standard of performance is defined (e.g. not completed in accordance with the Contract, defects in material or workmanship).
The duration of the warranty period (e.g. 12 months from take-over).
The remedy (e.g. repair or replace any defective parts).

Technical and Contractual Writing Tips

Now that we have covered some basics of contract structure and clauses, I have prepared a list of key tips you should keep in mind if you find yourself drafting, reviewing or commenting on a technical document or specification.

Tip 1: Accuracy

When reading any contract or proposal document you need to ask yourself the following questions:

Is the content accurately stated and factually correct?
Could anything be misunderstood?
Are irrelevant facts or other irrelevant information included which can be removed?
Are defined terms used correctly?

This is the starting point, because you are writing so that someone else in the future can read the document and understand the intention of the parties. Writing clarity and accuracy is critical!

Avoid

Confusing language

“The super-special product feature is an option at the customer’s choice.”

What does the above text mean in a contract? Is this special feature free or does the customer need to pay? When do they need to make the choice, before or after delivery? This type of vague language can be very problematic depending on the interpretation as the intention of the parties is not clear.

Making guarantees by accident:

The Seller’s product is best in class

Is this a performance guarantee? What happens if the product is not best in class, is that a breach of contract? Is it fraudulent misrepresentation? Does the Seller need to upgrade the product to constantly maintain best in class status?

Tip 2: Writing for Clarity

Precise language adds clarity about what each Party intended in a contract relationship. Try to write in a way that your elderly relative would understand and it is more likely that a judge or court would interpret it correctly if you ever end up in a dispute.

Avoid archaic terms (e.g., hereinafter, hereby)
Avoid legal pairs (e.g. good and sufficient)
Avoid Latin or foreign expressions (e.g., bona fide)
To the extent possible use plain language, not legalese.
You should avoid vagueness such as “provide reasonable assurance that” what is “reasonable assurance”? How would a judge interpret this meaning?

Don’t use “shall”, the word “shall” has several meanings that are easily confused, even by lawyers. Use the present simple tense, e.g. “The customer agrees to…”.

TIP 3: Obligations, Rights, Exclusions and Permissions

English has many ways to describe obligations, rights, exclusions and permissions. Use the table below to help choose the right word selection to match your intention.

To express…	Use…	As in…
Obligation (an order)	must, will	you must do it
Authorization (option)	may	you may do it
Prohibition (a ban)	must not / may not	you must not do it
Preference (a recommendation)	should	you should do it
No obligation	need not	you need not do it

TIP 4: Capitalised words

One of the most common issues I come across in technical documents is the incorrect capitalisation of words in documents.

A capitalised word mid-sentence in a contract has a specific use. This is done as a kind of shortcut or hyperlink to a defined term. Therefore if you capitalise a word without defining it, the reader will be confused and often start trying to find the definition.

There are two ways to write defined terms:

1. Include them in the definitions section of the contract.

“Services” means the installation and commissioning of the Low-Voltage Wiring.
“Low-Voltage Wiring” means the 12V DC wiring to be supplied by the Contractor under this Contract.

2. Within the text of the document itself.

The contractor will provide and install 12V DC wiring for the project (the “Works“)

You should use defined terms in the following cases.

As soon as you know you will refer to the same concept more than once in a document; and
When it takes more than a few words to explain the concept.

Conclusion

Learning the art of writing good technical documents is a journey that can take many years to perfect, but follow the golden rule: ask yourself, would your neighbour be able to understand what you wrote and the intention?

If the answer is yes, then you have succeeded in writing a good contractual attachment.

I hope the information provided here was useful to you and I have only scratched the surface of this topic. If you have any comments, suggestions or your own top tips don’t hesitate to add them in the comments below.

Happy writing all!

Charles Haworth