About Technical Writing - An introductory note
Introduction
Few writing practices such as Academic Writing, Research Writing, Patent Writing, and Legal Writing belong to the ‘Specialized authoring’ category, with definite rules and boundaries. These categories of writing require formal education/certification/experience on the same. For example, it is not possible to write or understand even a basic legal document without having an educational background in Law.
Unlike the specialized writing categories, Technical Writing is often confused with few other genres of writing in prevalence today - Content Writing, Instructional Writing, Business Writing, Marketing Writing, Creative Writing. This is because recruiters do not have clarity of what it means to be a technical writer and the field at large.
This article is an attempt to:
1. Briefly outline the journey of technical writing as a practice in Indian Software Companies.
2. Clarify the frequently asked questions in your minds if you are hiring a technical writer.
Story and Journey of Technical Writing
In early 2000, all the documentation written for the Software world came to be classified as Software documentation and the writers who wrote these documents were named Technical writers.
It is only well into the first decade did the industry really understand that the technical documentation such as Low Level Design, High Level Design, Product Functionality Documents, and other SDLC-specific documentation were still best handled by the project teams themselves, while reserving the user-facing documents such as Release Notes, Administrator Guides, Configuration Guides, User Guides, User Manuals, Complete Reference Books, Report Books, Fact Sheets, Data Sheets, UI Help Guides to be written by the Technical Writer fraternity.
With the software industry going through shifts in the way it operates and designs software products, the technical writing field also became adaptive to the latest requirements in writing. Organizations began to invest more into making content management systems, authoring tools, language editing tools, and publishing tools over the last two decades. The modes of distribution, the patience level of the reader, the newer software architectures, and the tools played important roles in Content Strategy for any software project management.
With that context set, we are now in a better position to understand a few frequently asked questions.
Frequently Asked Questions
What is Technical Writing?
The field of technical writing is to address a complex technical topic in a simple language for a pre-set audience with a specific level of knowledge.
Who is an ideal Technical Writer?
Anyone who likes to write (in the English language for Information Technology) with
background education in Engineering or Science is an ideal candidate for a Technical Writer profile.
What are the documents written by an ideal technical writer?
A technical writer writes the following documents for software products:
a. Release Note
b. Techno-functional Guides
c. User Guides
d. Configuration Guides
e. Administration Guides
f. Context-sensitive Help
g. Knowledge Base articles
h. User Manuals
What are the other documents the technical communicators write?
a. Technical Blog Articles
b. Issue Analysis Reports
c. Process documents
d. Newsletters
e. Product launch emails
f. Concept documents
g. Fact sheets
h. Web page content
Get Deepa Sriram’s stories in your inbox
Join Medium for free to get updates from this writer.
What is the process followed in Technical Writing?
Technical Writing follows Document Development Life Cycle:
Planning Phase
Project Planning: What is the project? When is the document needed? Who is driving it?
Audience Analysis: Who is the reader?
Requirement Gathering: What material do we have and what do we need?
Design Phase
Mind Mapping
Content Outline
Work Breakdown Structure
Development Phase
Knowledge Transfer
Draft One
Self Review
Diagrams
Review Phase
Technical Review
Review One
Revision One
Review Two
Revision Two
Content Review
Readability
Style
Redundancy
Cohesive Writing
Plagiarism
Language Review
Punctuations
Grammar
Capitalization
Spaces
Parallelism
Run-on
Word Count
Publish Review
Header and Footer
Copyright and Disclaimer
Table of Contents
Hyper-links and References
Page numbers
Release Phase
Third-Eye Review
Management Opinion
Rendering/Publishing Content in the format: PDF, Word, Wiki, Web page.
In the present day Agile world of development and solo writing experiences, it is upto the writer to ensure the process is followed. There is often no documentation manager or team to advise, guide or assist with writing-related challenges.
Are the steps mandatory?
No. The above list is an exhaustive coverage of the steps followed in a process-oriented organization for vast documentation projects. For lighter ones, the writer and the documentation manager, choose the required steps and complete the documentation.
Is there a specific style guide for Technical Writing?
Yes. The popular Style Guides in use are Microsoft Manual for Technical Publications and
Chicago Manual of Style. Companies needing extensive documentation prefer to keep their
own style guide. For an aspiring writer, Simplified Technical English (STE) proves a good reference.
How is Technical writing different from Other Writing Areas Business/Hobby/Instructional/Creative/Marketing/Academic/Research/Book?
A technical writing snippet counts in every word: Meaning, Need, Context are important to check if a word reads together with the text.
The readers should not refer to a dictionary to understand the words in the text.
The word count matters in technical documents based on the publishing medium and the document.
Audience analysis determines the depth of content in the document.
No use for frilly or flowery language.
Flesch Kincaid level under 7 is a good reading measure for techno-functional content. The number 7 shows that the text can be read and understood by a seventh-grade student in American schools. For technical content, the accepted limit is 12. If Flesch Kincaid level is above 12, it needs to be toned down in language and composition. Most writing software has a feature to measure readability levels.
Technical writing is to write only what is complete. Any planned development need not be mentioned in the main text. However, based on the company’s authoring standards, Conclusion can mention the features being contemplated or worked on. Exercise caution in giving out information on incomplete or progressive development for the wider audience.
Technical Writing does not encourage ‘feelings’ in the words. No expressive language is allowed in a formal document. This means to say that the emotional words stay in emails and product launches to an acceptable extent, but never in a User manual, Guide, Context-sensitive help and other such formal documents.
