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. As an Engineer and a Writer with 3 years of experience writing technical Runbooks and How-To documents in my engineering roles, I can help clients in this area. One should also consider my background in my prior career, as I have 15 years experience in financial operations designing and writing Sorbonne Oxley (SOX) compliant procedural/process documents; ergo my ability in-depth to ably help clients is present deepening know-how in this space.

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. That said, I would add in addition to inheritance, concept grouping and extendable index structures the following as a standard:

a) Statement and delivery thereof document objectives, context, and execution. This can be for linear and/or parallel processes delivered 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 of documents in a document construct that is meaningful and designed for the avoidance of repetition and clutter, which increases end-user experience in document repository navigation and use.

d) Development of document repository by means of the website via selected DITA compliant intranet offering (e.g. Confluence), web-based offering or from scratch builds. They should deliver a great user experience bearing the above in mind via centralized intranet or internet products.

e) Strict processes for technical document provisioning, drafting, reviewing, and approving that is version controlled and 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 their 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 with reading it and understanding its context, the correct use and resulting satisfaction with the subject software will rise to create happy end-users and a profitable product. 

Customer-facing documentation is often multi-faceted making the DITA approach essential bearing in mind that indexing structures, extendability, version control and audibility are just as much a requirement as the How To type documentation format with added video or static imagery to bridge the technical know-how gap for customers.

On a final note, the argument of Runbooks V How To Documents is an old one borne of out too little time spent creating technical documentation. Like customer-facing documentation, both require context, construct/approach and document goals to be set up to prep the reader in summary form for easy digesting of its contents, or swiftly move onto another document that addresses their needs. The key difference lies in scope. Runbooks have narrow scope to a single issue (normally a monitoring alert in production) with a low difficulty level and a relatively high probability of occurrence. The structured process flow will be linear and move through steps to diagnose, confirm, resolve and/or escalate the issue. This linear aspect of Runbooks is not shared by How To documents, which can be addressing more complex issues on a single or parallel process path. The complexity is driven by often very detailed technical interactions that are considered semi-structured at best and require a higher level of end-user technical competence to execute. How To documentation often covers processes that are not considered urgent or "production" related for the simple reason that good infrastructure (and systems) architecture mitigates complex issues going wrong by design in production leaving simple issues to normally be dealt with by the level 1 on-call engineer. More senior engineers use How-To documents to deal with more complex issues during normal business hours. 



Related Articles