top of page
Writer's pictureVinay Payyapilly

Better documentation: Articles as band-aid

Have you ever had to scroll through a long table that tries to explain the columns in a report? There is a very easy way to solve that problem, tool tips. As simple as it may sound, I have never been able to get any development team sign up for it.

In my current organization we solved this problem by using SmartTips in WalkMe. Using SmartTips, we can place the field descriptions as tooltips on the column headings. Apart from solving the problem of long tables in our documentation, it gives another unexpected advantage - we are not dependent on the developers to make any fixes. We simply create the SmartTips in WalkMe and deploy them. Later, if we need to edit any of the text, we are not tied to the release cycle.


Recently, while we were discussing how to solve customer problems someone suggested we get more documentation. To this the VP asked, "When was the last time you read any user manual?" A really good question. As a technical writer who makes his living off user manuals, I too often ask that question. Our job description is not to create as many articles as we can. It is to provide the user the information they require to complete a task with the least amount of resistance. This means finding the most optimal mechanism to deliver the information.


While the understandable knee-jerk reaction to any problem is to create an article, we should condition ourselves to try and develop solutions that does not require the user to leave the page or screen to find the information. More often that not, if the documentation solution is a complex one, then documentation is neither the problem nor the solution. It is the product that requires fixing. So while documentation can be a temporary band-aid, it is important to push for the item to be taken as a fix to be made in the next installment of the product.


It should be the aim of every software company to have as little documentation as they possibly can. The focus should be on making things simple and intuitive on screen. While new features are important, it should also be part of the company policy that every release improve at least one feature that creates support tickets.

Comments


bottom of page