It is January, 2014 and I am introduced to the world of technical writing. The task at hand: helping my audience understand the value of innovative business to business technologies. At a glance, the B2B technology market seems transformative:

  • Spurred by cloud, technologies such as big data, cloud, Internet of things (IoT), data analytics, Business Intelligence, and data visualization are in the boom.
  • Blockchain and Machine Learning are gathering steam.
  • Enterprise technologies are undergoing a sea change to meet the robust, agile, and high performance computing needs of competitive businesses.
  • In such a scenario, monolithic technology design does not cut it anymore.

Companies from across the energy, banking and insurance, legal, media, and logistics, defense, and more industries are investing in such advanced technologies. And, they want to be heard. As a technical writer, I am tasked to be their voice. The mission: helping the B2B technology decision makers(the target audience) make the right technology choice to solve their business problems.

Seven-and-a half years on, I have loved, lived, and cherished the job of a technical writer.

During this period, I developed stories with a natural narrative arc. A story would begin with a strong moot point and would steer the reader toward strong, evidence-based arguments. The story emphasized key pain points of the target audience and how the technology I pitched for would fill the gaps. The story not only helped the reader appreciate a technology solution but also understand how it would meet their unique business needs and the return on investment they would achieve.

Embracing the Other Side of the Fence

Fast forward to today and I am a documentarian. As a technical documentation specialist, I continue to write about both the worlds–cloud-native and on premise technologies. Each of them enabled with features such as data visualization, knowledge graph, machine learning, IoT, and web technologies. While the first seven-and-a-half years dealt with helping the B2B technology decision makers make the right choice, the last two-and-a-half years has been about documenting the working of those technologies as part of user help.

Documentation, My Perspective

What a find! What a place to be in! What fun!

I stand amazed at the very idea of documentation. While technical writing is fulfilling for me as a writer, technical documentation takes fun to a whole new level. In ways, technical documentation for me completes the meaning of life. No less!

Why? Documentation centers on capturing the action, capturing the truth. It is about communicating the truth to the readers to help them take better decisions. Summarily, it is about a record of truth that enables readers to act wisely and make their own life better.

Below is a snapshot of my observation and experiences in technical communication.

Topic Technical Writing Technical Documentation
Defining target audience Learning about who the decision maker is and how her day looks like at work Learning about the unique user persona and her role in the organization
Understanding the unique needs of the target audience Understanding her business problems and what keeps her awake at night Understanding her role and job responsibilities
Learning about the gaps the product fills Knowing how the client is projecting the product in the market Working with the marketing team and attending leadership meetings to understand what problems the company is trying to address for the customers
Planning content structure Cutting one big idea into smaller chunks and arranging them in a cohesive manner Understanding the sequence of user actions at the high level (User task workflow)
Transforming complex technologies into simple coherent ideas Writing the story with the intent to demonstrate how the product solves her (the reader’s) problems Working with Technical Product Owners to understand the problems solved for the end user, what the feature is all about, why it is important, at what phase of her work it is applicable, and how it works
Surfacing the moot point Highlighting the unique pain point of the reader and the details around it Understanding the scope of documentation, defining the table of contents for a feature, going from high level benefits to the instruction level walkthrough
Making the promise Making the big promise and diving deep into the intricate details of it by providing evidence of how the promise would be fulfilled defining the table of contents for a feature, going from high level benefits to the instruction level walkthrough
Narrative arc Making sure the big ideas are divided smaller chunks and arranged into logical sequence Tracking the sequence of end user actions, the user persona involved, and actions to be performed, step by step
Fulfilling the promise Circling to complete the story and showing how the product would bear fruit in the real world Showing the screenshots of how the user will see the feature/application results
Case study Before and after effect of the product Demo using dummy data and providing screenshots
Conclusion Reiterating the moot point and ending with a futuristic roadmap Documenting Note/Warning/Attention/Appendix to keep her (the reader) informed about unique conditions