How do you know, as a Technical Writer, when you are giving too much information.
Yes, one of the great things about the Internet is that you are not limited space-wise in the same way you are when creating actual, paper documents.
However, this can be a curse, especially when it comes to creating user documentation. The more you create, the thicker the forest of links and clicks grows, overrunning any semblance of a straight path from question to answer.
I was recently documenting software at my job for a component that displays a large table displaying financial statement data, among other things. The table can be filtered with drop-downs at he top of the page. The table headings are somewhat complex, breaking down into sub-levels of financial data. I addressed these things in the help but then noticed at the top of the page two icons.
One was a printer icon, one was an Excel icon. For some reason, in much of the help written for the software product I document with a group of about six other people, there are usually instructions for printing or exporting data to Excel.
In most cases, these icons are placed very visibly on the screen and don’t require any additional steps that someone who has printed a document or opened an Excel spreadsheet need to know. Just click an icon, both of which have tool-tips indicating what happens when you click them.
Still, out of habit, I started to write up my little topic about printing and exporting the table data to Excel. But then I stopped myself. It wasn’t necessary information.
I document advanced stock analysis software for the Financial Services industry. Everyone’s portfolio is screwed if the person who is managing my mutual fund is so confused by these icons they have to search help content for instructions on how to use them.
However, morel likely is the possibility that it is the other way, around, they don’t need step by step instructions on the how to click an icon, then click the ok button. But, there is a possibility they may not see the icon. They may not be able to find what they are looking for. In addition, the way the software is set up, there is a main toolbar menu that has a File>Print option. This prints out different things than just clicking the Print icon about the table.
Confusing, huh?
I decided to leave out the Print/Excel instructions, but, as I write this, I realize I was right and wrong. It’s not my job to explain the basic functions of computer use, but it is my job to anticipate confusion between the two print options.
So, the answer is show the user where the icons are in the help documentation, explain what they do, but tasked-based instruction is completely unnecessary.
