Do You Need Documentation for Your Custom Software Application?

Share on FacebookTweet about this on TwitterShare on LinkedInGoogle+

Share on FacebookTweet about this on TwitterShare on LinkedInGoogle+

A part of developing a custom application is creating the user guide and/or help files. Well, maybe it’s not so much a part, as it is an obligatory afterthought in most cases. Documentation can serve a true need for the use of an application or system, but sometimes it seems like more of a security blanket than a necessary deliverable. I would always urge a moment of contemplation on the need for documentation prior to engaging a technical writer in the weeks/months of screenshots and writing succinct blurbs about an application. First, you should ask yourself, “Do I need a User Guide?” and then reflect on your core needs (informational, procedural, obligation), how documentation will support those needs and then consider alternatives that may be vastly superior. Reading user guides isn’t a commonly popular thing to do; so many people tend not to. I once knew a group of engineers who used the term “RTFM” (an acronym for Please Read the Manual) whenever they faced somebody doing something incorrectly, which stemmed from the common lack of manual reading in the world. So whether it’s a business system or a home theater, there might be better ways to provide necessary information to a user than extensive documentation.

This Application is Complicated

I think the most common reasons for a user guide are to explain how to use a complex system, to show where key functionality and features are and how to perform common and necessary tasks within the system. That’s a solid reason for creating a User Guide, but it’s also a sign that your system doesn’t have an intuitive interface, or that it isn’t designed to serve the customer’s existing business processes. User Guides don’t tell a customer how to do their job; they know that already. If it’s well-designed, easy to use and makes sense in the business context for which it was designed, you really shouldn’t need a document.

This Application is New/Different Than Our Old One

So you’re modernizing; tossing out an antiquated system developed in the 1980’s and replacing it with a slick new web-based one that will drastically improve your productivity. However, your staff has been indoctrinated into the old system and there is going to be a steep learning curve in the transition. I get that, however, does that necessitate a user guide to accompany the system throughout its life? In this scenario, you really need a training guide, something designed to be ingested in one focused sitting, perhaps with some live system demos. Once your staff has passed through that initial transition to the new system, they won’t have a need to refer back to a user guide. You can meet your need here with a light, interactive training document, instead of a heavy effort to document an entire application. For future versions you can provide documented release notes which capture bug fixes, new features, or other modifications that impact the user.

We Should Have a User Guide of Some Sort; it’s Just Expected

I’m a creature of habit myself; I see the world as one of order, place and belonging. Maybe, deep down, you feel that anything technical should have an associated reference document. In that case (which I find to be the most common reason a user guide is written), it’s important to determine what information to capture. What parts of the application need a reference; maybe password conventions, permissions levels, and/or help desk contact information. Determine exactly what needs to be documented to keep that effort focused and cost effective.

User documentation often seems like an IT security blanket that isn’t worth the added cost to project hours, both for initial development as well as updates for future versions. Users aren’t inclined to read them and once released, they require updates whenever your evolving system is updated. Keeping documentation scoped to just the key information saves a tremendous amount of effort, up front and down the road and also makes it more effective and easier to digest.

Need Help? Contact us

Share on FacebookTweet about this on TwitterShare on LinkedInGoogle+

About the Author

As Segue’s Chief Strategist, Matt focuses on proposal development and capabilities marketing to align our experience, current capabilities, and resources with winning solution strategies. He works closely with Segue’s business leaders to build robust opportunity pipelines for each of our verticals: US Air Force, Federal Non-DoD, USN/USMC, Health IT, and Commercial/Non-profit. In addition, he is focused on capturing major IDIQ vehicles and capabilities to respond to a heavy pace of Task Order requests for proposal (RFP). Read more from Matthew Kelley