The symbiotic relationship between documentation and application development

One of my current projects involves documenting processes for an application that are still under development. As such, much of what I write may change, depending on how processes are changed during the course of development.

At one point, I tested one of the processes so I could determine functionality and document it. In doing so, the process came back with an error message that I wasn’t expecting and didn’t have any user-friendly information, other than a cryptic error code. I contacted one of the developers working on the application and told him what I found. I gave him the error codes I experienced and steps I took to get them. He told me, “you’re coming across bugs that we didn’t even know we had.”

It occurred to me that I was doing more than just documenting the application. I was also acting as a beta tester.

One aspect about writing technical documentation is learning about what you’re writing. In order to write about a process, you need to understand how it works. If you’re documenting an application, the best thing you can do is run the application in a safe environment (such as development or a sandbox), learn how it works, and use it to document steps and capture screens. In doing so, you come across application bugs and even come up with ideas to make the application even better.

I’ve long argued as to the criticality of documentation. It records important information and serves as a reference. However, until this point, it didn’t occur to me that the document development process could have a symbiotic relationship with application development. To me, this adds further fuel to the argument that documentation is critical and required.

Advertisements

Don’t forget to edit your system messages

One of my current work projects is a administrative guide for our application. After a recent status meeting, one of the developers sent me a list of validation error messages that might appear during data imports. I was asked to make sure the validation messages were included with the documentation.

While going through the validation messages, I noticed that they were filled with grammatical, capitalization, and spelling errors. I asked the developer if he wanted me to edit the messages, to which he responded, “yes, please!”

People don’t think about checking output messages for correctness during application development. It is often a part of applications that is overlooked. For what it’s worth, I, myself, didn’t even think about it until I was asked about these validations. Nevertheless, reviewing and editing output messages is probably a pretty good idea.

For one thing, and I’ve stated this before, good writing reflects upon your organization. Well-written documentation can be indicative that a company cares enough about their product and their reputation that they make the effort to produce quality documentation as well. Well-written system messages indicate that you care enough to address even the little things.

Well-written error messages can also ensure better application usage and UX. A good output message can direct an end user to properly use the application or make any needed adjustments. Messages that are confusing, misleading, badly-written, or ambiguous could potentially result in things like application misuse, corrupted data, accidental security breaches, and user frustration.

Ensure your application development review and testing also includes a review of your system messages. It may be a small thing, but it could potentially address a number of issues. As someone once said, it’s the little things that count.