Tag Archives: documentation

What’s your problem statement?


A problem statement is a means to help build censuses and align stakeholders on a common direction to solve a problem.

The purpose of this post is to share practices to communicate a clear and concise problem statement.


The scope will cover a simplified template that can fit on a single sheet of paper or on one page in a presentation.

Out of Scope

If you are looking for detailed problem statement formats or processes (i.e. LEAN & Six Sigma) or details on reframing the problem statement there are pages available that cover this, some of which I added below.

In this post I am really focusing on the simple template that highlights the key points of a problem statement.

  1. How to write a problem statement — Detailed walk through
  2. Examples of re-framing the problem and including impact details — Simple examples so I do not have to reinvent the wheel with new examples
  3. 5 questions to ask when re-framing the problem 


In my experience Problem Statements are commonly used to influence people to work together to solve a problem.    But not all problem statements are created equal and have found many are only statements or problems that leave me confused and in a meeting where we waste time talking about a scenario where:

  1. I do not agree is a problem or
  2. the impact is unclear or
  3. we spend a meeting talking about a problem we agree on leaving no time to talk about what the solution would look like.

Problem Statement Template

The template comes from an example on Jama’s product overview video.

This template was short and sweet and covered the key ingredients to a problem statement I had not seen presented in this manner.  Since seeing this I have used it several times to help ensure I am telling a clear story to stakeholders.

Problem Statement Example
Problem Statement Example (Source jamasoftware.com)

When discussing problem statements with others you want to make sure you are building census.  If people do not agree with the problem statement they will most likely not be aligned on the efforts you are pitching to solve the problem.

In the next sections I add comments about each section of the template and remind you about the point, are you building consensus?  Are the stakeholders all in agreement of the overall statement?

The problem is….

Try to keep as simple and concise as possible.  Avoid adding your personal perspective and make sure to be objective.

You will most likely have more material that goes into the details, so keep this section short and clear.  And above all, make the audience agrees this is a problem and the problem we should be working on.

The impact of which is…

This is where you state the impact, the “So what?”  You want to start building consensus and this is where you want people to start thinking:

“Dang, this is really a problem!  We need to do something about it!”

A successful solution would be…

This is the punch line and should be stated on the same page as the problem and impact.  Make it clear what a solution looks like.  You will have to balance the “what” & “how” perspectives based on your situation.  But do not wait for the end of your presentation to show what you are looking for.

Feedback is your friend

Chances are the first time you show this to someone they will give you feedback, something they do not agree with or details which are too much into the solution space.


Feedback is needed to improve the problem statement definition and ensure the correct perspective, impact and solution are aligned with stakeholders.

If you try to plow through into next steps of implementing the solution without re-aligning on the perspectives of your stakeholders you should expect some hiccups.

In scenarios where it is not reasonable to get 100% consensus, disposition the concerns that will not be addressed and state the rationale for not addressing them.  You can also considering breaking the problem into a set of problems and solve one at a time.


The example used by Jama provides a simple template for stating a problem statement.  I have used it several times to ensure the essential pieces; the problem, impact and solution, are captured.



Conceptual design of implementing a Software Architecture Document with Atlassian Confluence


This blog post showcases a conceptual design for implementing a Software Architecture Document (SAD) in a Atlassian Confluence Wiki.


Share the design concept to a broad audience by publishing online.


Defines the initial steps for creating Atlassian Confluence (will be referenced as Confluence from here forward) wiki pages aligned with the SAD example provided by the Software Engineering Institute (SEI).


I was working on a project which was getting into a documentation problem.   I wanted to know the common practices in industry and started researching documentation practices for software architecture and systems.  The research led to the ISO/IEC 42010 standard, SEI’s contribution to the topic and the related Documenting Software Architectures: Views and Beyond book on the same topic.

In the specific project I was working on, the direction was to use Confluence for documentation.  While I had been regularly publishing to the wiki and benefiting from using the Macro and Template features, I wanted to dive  deeper into what Confluence had to offer to understand how the concepts of the SAD can be applied to the wiki to provide a documentation solution requiring a reasonable effort to maintain and scale.

Design Description


The flow is for the publishers of the documentation to start with the SAD Microsoft Word template, import the template into Confluence, create Confluence Template Pages, and add sections to Confluence using Confluence Templates as the architecture changes over time.


The remaining parts of this section describes the implementation in more detail.

Initialization and Addition of pages

The intended flow is as follows:

  1. Publishers download the SAD Microsoft Word template,
  2. Publishers edit SAD template and save
  3. Publishers import SAD document into wiki
  4. Publishers add Viewpoint Definitions, Views and View Packets using Templates.

Template Design and Macro Usage

This section provides a structural view of the wiki modules used in the design.

The UML Class Diagram below shows the templates and macros used in this design.

Class Diagram
Class Diagram


The UML Object Diagram below shows the pages that would exist for a scenario where there are two Views, each View having two View Packets.

Object Diagram
Object Diagram