Has Technical Writing Evolved?

Source: http://www.thebluediamondgallery.com/wooden-tile/e/evolution.html

I have been curious to know the history of technical writing for some time. That is when I stumbled upon this great write-up done by ClickHelp [1]. It describes how Aristotle is believed to have the first form of technical documentation. How cool is it to have the “Father of Western Philosophy ” as the founder of technical writing!

From then to now, content seems to have evolved along the way. Content Philosopher, Joe Gollner mentions that we are now in the content 4.0 era. For those of you who are not familiar with it, take a look at his blog [2].

Source: http://jgollner.typepad.com/.a/6a00e54f8d0913883301b8d2a1ad00970c-popup

What was technical writing like 10 years ago?

This was an interesting topic that my colleagues at WSO2 were discussing. Most of them have over 10 years of experience in technical writing. Back then, technical writing was not so commonly known. Yes, it was a much-needed area for organizations but their tasks were distributed among writing technical documentation and other roles.

A common form of documentation was shipping the documentation along with the product in the PDF format or as a .txt file. A drawback of this approach is not being able to change the content once the product is shipped to a customer. If you need to update the documentation, you need to release another product version. What a nightmare :O. This approach works for fairly simple products, but what about complicated products?

What is technical writing like today?

If you don’t have accurate and quality documentation… Sorry… your organization might not have a competitive edge. The competitors are going to pull you down fast (like a dinosaur bitting you into pieces — dramatic much)! Having good documentation and content is vital. Isn’t that a change from what it was like 10 years back? :)

That’s not it, technology has evolved so much (am not just saying this so it sounds nice, it really has)! There are so many tools we can use to document content. We don’t have to stress out on making changes to docs once the product is released because of tools like Confluence, GitHub documentation, Read the docs, and much more. It is important to provide accurate content but we all know that creating quality content takes a few cycles. Therefore, improvements need to be made along the way. The documentation tools that are out there help us achieve our goals and helps us go agile.

Evolution of content

Single sourcing content
Remember the time where several files were maintained to store content? Organizations are now looking at single sourcing (centralized) content . This method is very efficient because you don’t have to maintain the same content in many places. You can document the content in one place and pull the same content to other pages. This saves a lot of time when you need to update content. All you need to do is update one page and all the other pages are updated in one go.

Static to interactive documentation
Most content are static documents. But now customers and end-users are looking at content they can read and try out then and there (I call it interactive documentation). API documentation is a good example for this. Take a look at my blog on Static to Interactive API Documentation.

Animated diagrams
At times, writing many words or paragraphs does not get the message across to an end-user. That’s when we use diagrams. For example, it is easier to use architecture diagrams to explain the architecture of a product. Sometimes, that too can make it hard to explain the flow. Now, we see many docs having animated architecture diagrams explaining how the data flows from one end to another or the events that get triggered when using the product. This is pretty cool!

End-users can get confused when they have to follow many steps to get a task done (even though it is recommended not to have more than 10 steps…sometimes it is inevitable because you need all those steps). To help users not get confused, you can break the steps to sets of sub-steps and incorporate GIFs in your documentation.

These are a few things that came to my mind when I thought about how documentation has evolved. :) You will probably know other areas.. Share your thoughts!


[1] https://medium.com/level-up-web/history-of-technical-writing-9a895b4514ab

[2] http://www.gollner.ca/2016/12/content_4-0.html