Image of workstation used for technical writing

Technical Writing

Writing Style

One of the gaps that seem to never be fully filled in the software development lifecycle is documentation. How to use a software feature, a process, or a program?? These questions are often afterthoughts for Software Developers and Engineers as software is built, tested, and deployed under extreme time pressures. There are many understandable reasons why; yet the end-user will always suffer under the impact of the resulting knowledge gap around software use when all is said and done. This is where the Technical Writer comes into play. 

Technical writing has some references and standards like the Darwin Information Typing Architecture (DITA) standard or the Chicago Manual of Style for grammar and punctuation. In addition to these standards detailing features such as inheritance, concept grouping and extendable index structures, we would note the following features of our own technical writing service:

a) Statement and delivery thereof document objectives, context, and execution. This can be for linear and/or parallel processes documented in a clear and concise manner, using imagery if required to support understanding and ease of use by the end-user.

b) Clear and concise construction of sentences to deliver meaning with repetition removed in the document content. 

c) Referencing and indexing documents in a document construct that is meaningful, designed for the avoidance of repetition and clutter, and increases end-user experience in navigating a document repository.

d) Development of document repository by means of a selected DITA compliant intranet system (e.g. Confluence), a web-based offering or from scratch builds.

e) Strict processes for technical document provisioning, drafting, reviewing, and approving that are version controlled along with being auditable.

f) Internal controls sewn into user process flows with auditable management/peer approvals where appropriate. The idea is to guard against financial and non-financial risks in an auditable manner.

g) Implementation of a complexity rating system to inform the reader of the technical baseline required to understand the document content; as not all complex niche technology can be demystified for the end-user. This applies mainly to internal technical documents for end-use by customer service, support, and/or engineering staff.

The document flow is key to all of the above and once the reader is comfortable reading it, the correct use and resulting satisfaction with the subject software will create happy end-users and a profitable product. 



Related Articles

image of a project timeline for a Maolte Technical Solutions Limited article on major incidents and digital migration

Major Incidents and Digital Migrations

Image of Jenkins workflow

CICD and Jenkins

Image of a runbook template header on Confluence for technical writing purposes

Effective Technical Documentation