This article teaches how to write the first sentence for the HLD document, so software engineers and technical writers can precisely convey their intents to readers.
The first sentence sets the tone for the whole HLD document. It helps readers and writers both. Readers gets the basic information before reading more. Writers gets the direction throughout the whole writing process.
You can naturally get the first sentence by performing these four steps:
- Identify the promise.
- Identify the audience.
- Identify the Impact.
- Assemble your analysis.
The first three steps involve pure analysis, and the last step turns analysis into words. I recommend do some analysis before assembling a statement. You spent not much time but gain a lot.
Identify the Promise
The promise is what the document about. When the audience read the first sentence, promise them something. For example,
This document provides a design for … system, explains …, describes …
If the promise does not appear in the first sentence, the reader has to digest more and may give up when losing patience.
The promise limits the scope of the document. In the following writings, you can delete any irrelevant texts.
Identify the Audience
The audience is whom uses the document. Explicitly stating the audience helps readers determine their relevance with the document.
If the audience does not appear in the first sentence, the reader has to keep thinking how they use the document.
You may have more than one audiences. If so, try analyzing their impacts individually.
Identify the Impact
The impact is how the audience do with the document. Help audience find out their impacts.
If you don’t know their impacts, try your best to find out, such as scheduling a meeting, running a workshop, doing some interviews and making phone calls.
In general, the impacts include planning, budgeting, resource allocating, researching, etc. Depending on the roles or job titles, the decision varies.
If you don’t provide the impact, the reader may make a quick decision: skip this for-your-information (FYI) document.
Assemble Your Analysis
Assemble your analysis using simple joining words. You can assemble your analysis in a thousand ways. But using simple joining words makes readers less distracted.
You can edit the first sentence later when drafting the entire document. But you must have your analysis done right first.
For example:
This document provides a design for a serverless database (promise), so hackers (audience) are able to launch their projects with low-cost while achieve high availability and high throughput goals (audience’ impact).
“This document”, “so”, “while” appear as simple joining words.
