Use cases and technical documentation

What use cases are

A use case describes a sequence of interactions between a system and an external actor that results in the actor being able to achieve some outcome of value (Karl Wiegers and Joy Beatty “Software Requirements”, third edition, August 2015).

Technically, these are requirements specifications resulted from a thorough analysis and a number of discussion iterations with Product Owner and the development team (software architects, most probably).

Use cases give all parties (Product Owner, development team, as well as technical communicator) a clear overview of what functionality and interaction types between actors and a system will be implemented. The textual description of such interactions provides a precise picture for a Product Owner and other stakeholders that shows what their solution will be in line for and how exactly it will be happening.

Within the roles performed in the team that is involved in development and delivery of a software product, designing and writing use cases is the task of a a requirements specialist.

And you, an information developer, should understand the true worth and value of use cases on a project and try utilize them to the fullest extent.

How you can benefit from use cases

A requirements specialist with their well prepared and accurately maintained use cases comforts the entire team, including an information developer. If we observe the case of a sprint-like approach to continuous software development, then the stage of compiling and finalising use cases is one or more sprints ahead of the actual development.

This means that already at the beginning of the sprint, when it’s time for you to get down to writing user instructions or any other types of documentation, you are blessed with a substantial pile of information to analyze and dwell your writings upon. This is particularly useful when you are not given a chance to communicate with the users or even a Product Owner, but are expected to prepare a clear-cut topnotch document.

Use cases give you an understanding of true business needs, as well as ensure a wide and solid perception of the solution user personas. Knowing your users to the core, their pains and daily workflows, helps to provide well-aimed documentation that would satisfy their needs.

Even though use cases are structured in their own way (as your requirements specialist’s target audience and purpose of writing differs from yours), they are an invaluable source of truth. Based on use cases, you can test the solution yourself: perform UI walk-throughs until you feel you completely understand the solution and users so that you could proceed to creating your manual.

No more disturbing interventions into your devs’ routine with multiple questions regarding business logic. If you have a highly dutiful requirements specialist on a project, your hands are untied. You can start with performing documentation analysis and then proceed to creating your content taking into consideration your readers peculiarities.

On the other hand, most probably (and this is a common practice), use cases would lack UI names, specific details such as database table names or API parameters used. This is obvious, as at the beginning, when the solution is being designed and planned, details like that won’t necessarily be included. These are up to your solution architects and developers who take decisions as the work moves on.

So, for the internals, of course, you would need to arrange separate sessions with engineers to show down. However, solution and user analysis, document structuring, and precise section-based estimation can be conveniently done with the help and on the basis of expedient use cases. Use cases make both the project and documentation planning skeleton.

Where you can read about use cases

Below are some sources where the concept of use cases is very well described, and multiple examples are provided:


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s