Web Applications – make this clear to users at all times: where they are and what they are using

When a user experiences a problem using an application, the list of possible issues can be lengthy depending on the complexity of the environment(s) and dependencies.  If the user is unable to clearly articulate to the help desk what application is broken or where they are when issues arise then this is a clear indicator that the training, documentation and application itself are not all using the same language.

Make things easy for your users by following these simple steps with every application your write and/or support:

  • Give the application one name and one name only. In this example we will give our application the name “Blue Safari”.
  • Place the name of the application prominently on every page of the application. This means “Blue Safari” is on every page of the application.  (not “Bls Version 2.0” but “Blue Safari” or “Blue Safari Version 2.0”)
  • If your application is a web application, try to place the name of the application somewhere in the url if possible.
  • All shortcuts or hyperlinks that take users to the application should be the name of the application (i.e. “Blue Safari”)
  • In all documentation and training for users and support staff, refer to your application with the same language. This means all references to the application will be stated as “Blue Safari”.

If you give your application several different names then several problems arise:

  1. The user either doesn’t know what to call the application when he or she calls the help desk to report the problem or the user calls the application by a name that no one at the help desk recognizes.
  2. A significant delay occurs before the issue is resolved simply due to the time spent sorting out the confusion over what exactly is broken and where it is.

Avoid contributing to the overall mayhem of our existence, it will only end badly, we both know that.  Unless of course your help desk gives out free ponies and chocolate ice cream with every call, then maybe as a caller I will not care so much that I am unable to clearly tell you what is broken.  Now I want ice cream.

Why Application Documentation is so Important

Any application written, no matter how large or small needs documentation.  It doesn’t have to be fancy but the documentation must be written and it must be kept up to date – no exceptions.  The documentation can be as simple as a one page document that spells out to anyone who supports the application the following things:

  1. What the application does, how it works
  2. Who uses the application
  3. Where the application lives (server names/passwords)
  4. Databases it relies on (server names/passwords)

If this information is not documented (and the documentation not kept up to date), then troubleshooting the application may take hours which means the users are left waiting for (sometimes critical) applications to be fixed.

This is a typical scenario of what can happen when documentation is not updated (it happened to me yesterday):

We have a vendor written application that resides on two servers and it has several passwords and databases.  Years ago when I was a part of setting up this application, I documented everything about it.  I wrote a short one page document of all the critical stuff: how it worked, its databases, passwords, and server names.  Then, a few months ago, another team member upgraded this application and put the application and its databases on new servers.  Did this employee document any of this? No. Is this employee still with our company so I can ask him anything about this application? No.  Are we in a bind because of this? Yes.  Do you know why? Because the application went down yesterday.  We looked at the documentation I had written about the application and discovered it had not been updated so we didn’t know any of the new passwords for getting into the administrative side of the application; we actually had to hunt and peck through the registry to find this information.  Troubleshooting this application yesterday was a complete nightmare and it took several unnecessary hours.  If the documentation had been properly updated, it would have saved us hours of frustrating work.  The fix was something so simple (a particular executable had to be running 24/7 before the application would work and this executable had stopped due to the server getting hosed due to the a/c going out in the server room) but since no one had documented this new process, we had to figure it on the fly which kept our users waiting.

Many IT employees will complain that they do not have time to write documentation or update documentation.  The only reason they do not have time is because they either don’t make it a priority or the clients don’t understand the importance of the documentation.  IT has the power to address both of these issues head on by making documentation a priority and letting clients know that if they want fast service in a stable application environment, then documentation needs to be considered as important as the application itself.

Blog at WordPress.com.

Up ↑