As a Software Developer, the main goal is to create and build products that make life a little bit easier for others. Whether through creating cash apps like Abeg or making health apps like Tambua . In as much as we create software products, we need to know that all shareholders are able to properly use the application and maximize it. For this reason, technical writing skills usually come in handy.
Software applications need a variety of documentation. Types of documentation include:
- Requirements – Statements that identify the attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what will be or has been implemented.
- Architecture/Design – Overview of software. Includes relations to an environment and construction principles to be used in the design of software components.
- Technical – Documentation of code, algorithms, interfaces, and APIs.
- End-user – Manuals for the end-user, system administrators and support staff. Marketing – How to market the product and analysis of the market demand
Documentation is important because it ensures all sharers can use the product and understand the product whether technical or not.
Introduction
In this day and age where there is an increasing number of digital products, technical writing skill is becoming one of the most coveted skills. In fact, the U.S Bureau of Labor Statistics, states that the employment of technical writers is projected to grow 7 per cent from 2019 to 2029. This is faster than the average for all occupations.
While writing technical articles and documentation factors and elements to consider include:
Rules in technical writing
- Shorter documentation reads faster than longer documentation.
- Shorter documentation is easy to maintain.
- Extra lines of documentation introduces failure points.
Audience
Before writing any article or documentation you need to:
- Define your audience.
Identify the roles of your audience such as whether they are Software Developers or Program Managers among others. - Determine what your audience needs to learn.
List the things that your readers should be able to do after reading your article. - Fit the documentation to your audience.
Create explanations that satisfy your audience's curiosity rather than your own.
If you can't explain it to a six-year-old, you don't understand it yourself. Albert Einstein
Knowing your audience allows you to know the appropriate language in terms of vocabulary to use. Additionally, you know what concepts to explain and those to skip.
Terms
In the event that you get to use unfamiliar terms there are two tactics highly recommended:
- Do not reinvent the wheel, if the term exists link it to a good explanation.
- If you are introducing the term, define it.
In case, you are introducing a lot of new terms use a glossary.
After picking a term use it consistently to avoid confusing your audience.
Acronyms
Acronyms speed up the writing and reading process. When using an acronym for the first time define it then use it later.
Acronym Guidelines
Define the acronym if :
- It is shorter than the full term.
- It appears several times in the document.
Pronouns
Nouns are naming words for example Michael is a Machine Learning engineer. Michael in this case is the noun. Pronouns are words that take the place of nouns, for example, He especially enjoys Machine Learning Algorithms. He in this case replaces the name, Michael.
Pronoun Guidelines
- Use a pronoun only after you have introduced a noun.
- The pronoun should be placed close to the noun. If more than five words separate the noun and pronoun, repeat the noun.
- If a second noun is introduced between the noun and pronoun, reuse the noun.
Active Voice
The active voice describes a sentence where the subject performs the action stated by the verb. Using active voice is preferred to passive because it has the following advantages:
- Reduces the readers processing time
- Reports actions directly
- It is shorter than passive voice
Passive voice is still allowed but on a need basis and should be used sparingly.
Examples in Sentences
Passive voice: Code is interpreted by Python, but it is compiled by C++
Active voice: Python interprets code, but C++ compiles code.
Some sentences may also contain a mixture of both Active and Passive e.g Performance metrics are required by the team, though I prefer wild guesses. The first part of the sentence above is Passive while the second one is Active.
Simple formulas to help differentiate passive and active voice:
Active Voice Sentence = actor + verb + target
Passive Voice Sentence = target + verb + actor
Lists
Lists that dominate technical writing are:
- Bulleted lists
- Numbered lists
- Embedded lists
Bulleted lists are used for unordered items whereas numbered are used for ordered items. Embedded lists contain items stuffed within a sentence. For this particular reason, they are discouraged.
List items should belong together in regards to:
- Grammar
- Logical category
- Capitalization
- Punctuation
Tables
Analytic minds love tables especially while comparing one concept to another.
Table Guidelines
- Give the table context.
- Label each column with a meaningful header.
- Avoid putting too much text into a table cell.
- Strive for parallelism within each column.
Sentences
Sentences are the foundation of your article. While composing sentences consider using strong verbs instead of regular verbs. Verbs are important because once you choose the correct one the rest of the sentence will take care of itself.
Reduce subordinate clauses. Clauses are an independent logical framework of a sentence that contains an actor and action. In general, sentences contain the main clause and other subordinate clauses. Subordinate clauses tend to use phrases like which, that, etc.
Paragraphs
Opening sentences in a paragraph should be really good since they establish a central point. Paragraphs should only focus on a specific topic. In terms of length, paragraphs should neither be too long nor too short. Good paragraphs answer three questions:
- What information you are feeding the reader?
- Why the information is important to the reader?
- How should the reader use this knowledge?
Punctuations
Punctuations are important because they tell the reader how to read your article.Due to this reason use commas appropriately. They should be used when there are short pauses. Em-dashes on the other hand are used when there is a long pause. Use semi-colons to unite highly related thoughts and parentheses to hold minor points and digressions.
Final Thoughts
Technical writing is an art that involves using words that are easy for readers in the target audience to follow, understand, and act upon. And like art, it's a skill that needs to be developed. It does not happen overnight. It takes putting in the work like doing research and being consistent.