top of page
Writer's pictureVinay Payyapilly

The evolutionary journey of product documentation



Product documentation is key to the success of any product. I know that it’s akin to saying diet is key to weight loss. But like all truths, this one too is not understood properly. To understand it, we need to trace how documentation evolves in an organization. 


When a product is young, the product managers play the role of documenting how to carry out tasks in the product. This is usually done over email or phone calls. Eventually, the PMs begin to maintain MS-Word documents with answers to common questions on their computer. Over time, these documents are moved to a common repository or shared folder. This is the first iteration of the Help portal.  


As the product grows, answering customer queries becomes a drain on PM time. It is at this point that the company begins to think about a specialist role for this task. The solution is either one of the PMs stepping up to that role or bringing in a documentation specialist. Depending on the type of product, the output will either be a Help file that goes with the product or an online Help site.  


At this stage, it is important to think about processes and standards. For a start-up this is a difficult transition to make. People are used to wearing different hats. They are also used to walking up to a colleague and getting their work done. These habits have worked well until this point, so nobody sees any reason to change them. Very much like saying – Don't fix what isn't broken. But in a growing company, such random ways of working lead to uneven results. It’s broken, we just don’t know it yet. 


One of the things we need to start considering at this stage is a ticketing system. No matter how rudimentary, this is a must-have. It ensures that things don’t fall through the cracks. While ad hoc ways of working give a sense of swift action, they are notoriously porous. It also opens up the possibility of personal relationships deciding the priority of items.  

The simplest scheduling system is to use a combination of to-do lists and the calendar. The intention should be to move towards a process where we can project headcount requirements, delivery schedules, and workload.  


Ticketing systems such as JIRA, Asana, Trello, are also a great way to ensure both work continuity and retaining team knowledge. If we record all information pertaining to an issue within the ticket, it becomes reference material for posterity.  


In an earlier organization, we had a big, ugly “i” icon on the UI. In one meeting the UX person asked in a voice filled with pain and frustration, “Why is that ugly thing there?” I was the only person who knew the answer. The whole room looked at me in surprise. It was then that I realized that there was nobody in the room who knew that history. 


Action is a default human behavior. When faced with a problem, our instinct is to get going on the solution rather than trying to identify the real problem. Processes, it's great to talk about them, but they are also terribly difficult to implement. Often, they are seen as getting in the way of productivity. In most cases, we pay lip service to the process but when push comes to shove, we never follow the process. 

Comments


bottom of page