Frustrated Analyst

Throughout their careers, analysts work on many projects in multiple business domains, mostly for different organizations. Joining a new company or jumping on a running project requires an analyst to quickly go through supporting materials and soak in as much information as possible in a limited time. Since this might represent a lot of information, the learning process must be top-down, going from general facts to details. Therefore, what analysts always start to look for are general domain descriptions, business and IT architecture overviews, process maps, and business terminology explanations. What they usually get, though, is a bunch of detailed documents, diagrams, and other materials, which are not interconnected and which instead confuse them.

"But the project is moving forward and has already delivered several solution components, so it cannot be that bad, right?" Yes and no. First, it is very likely that the project is not performing as well as it would if it had quality documentation. Second, during projects, people get used to using even poor documentation since they have no other choice. They learn to navigate in its clumsy structure or to recognize which parts are reliable and which are not. Also, after spending a couple of months on the project, people simply learn the terminology, processes, and systems by heart. The poor documentation does not represent a problem for them anymore since it is used on rare occasions and just to reference some complicated stuff. For example, the key process documentation could be useful even though it is buried in a document called FS20170526-A.v23 and is all described in the text, which takes 2 A4 format pages. People simply learned how to use it. However, the situation changes when the new team members join the project and want to get on board as fast as possible. The problem also arises when the process documentation is part of the overall enterprise architecture documentation, which is used by dozens of people. In this case, every minute, the bad documentation adds to their learning process, costs money, and causes frustration to those who need the information quickly.

Sources of Frustration

This section describes what we consider to be the most common reasons why people get frustrated when reading documentation written by somebody else.

Missing Documentation

Obviously, it is frustrating if critical information is not available at the right time. It is because project teams and organizations often do not keep track of what they know, which is mostly for the following reasons:

1. Documenting is a Bore

Analyzing and implementing software is fun. Creating documentation is not. It is time-consuming, and when it is not clear what to document, where to put it, and how to structure it, it is not fun at all. But we believe that documentation is usually "postponed indefinitely" not because analysts are lazy but because they do not know what to document, when to document and how to document effectively. In the following chapters, we are going to answer all these questions.

2. "It is in the source code"

In this section, we have talked about the agile approach to software development, described how it differs from the traditional processes, what are the fundamental principles and how it helps to be more productive. Unfortunately, agile is often misinterpreted. The foundation of agile, the agile manifesto, states: "Working software over comprehensive documentation". This is very often taken as "Documentation is not needed, source code is enough." But the manifesto does not say: * "Working software instead of documentation." The source code will never give an overall picture of the problem, nor will it answer why something was implemented the way it is. What is more, source code as system documentation possess also following additional limitations:

1. It is undoubtedly faster to locate a model or a function overview to find out information than to search through the source code
2. Source code says how the application works not why it works that way
3. Source code is the lowest level, which is mostly not needed
4. Source code documents just the behavior of the single system. There are also other essential parts, such as how the system is integrated with other systems, what communication flows exists between them or what data the system stores. This cannot be discovered from the source code in a reasonable time.

3. Verbal Specification

Some analysts, in good faith they are genuinely agile and that it will increase their performance, do not create any specification, so the solution development is based on what analysts told developers to build. Although it may work quite fine in specific environments, it by no means could be considered the right approach in general. It is incredibly effective to develop software this way. Still, only when the development team knows the business domain and the related systems, so they can understand and implement the changes with no or minimal specification. However, despite the working solution is the team's primary goal, it is not the only one. The secondary goal is to enable the next effort, which means allowing the others to support the solution, modify it, or extend it. This goal will inevitably require creating at least some documentation and let's be honest, will the team remember all vital information if the documentation is postponed after the project is finished? Would it not be better to capture the core facts during the development?
Besides, people supporting the solution are not the only persons who might be interested in what the team has built. There will certainly be people in the future who will need to understand the solution from the perspective of the whole enterprise. They will ask how the enterprise benefits from it or how the solution integrates or supports other enterprise components. This is why the solution documentation cannot be a solitaire and should be incorporated into the overall enterprise architecture documentation.

Outdated Documentation

The team successfully finished the project, changed two processes, added a new module to the core system, and integrated a new external service. They threw a big party because everything finally runs smoothly in production. What they forgot, though, was to update the documentation so when somebody needs to learn how the two modified processes work, they will only see the state before the project implemented the changes. They either know about the changes and will ask the team for an explanation, or in the worst case, they will rely on the wrong information.

REMEMBER

Outdated documentation is worse than no documentation.

Therefore, updating documentation must follow each activity, which has made changes to the as-is state of the enterprise.

Too Detailed or Too General Documentation

It would certainly be great to have documentation of every single aspect of the solution or enterprise in general. But as the missing documentation is terrible, the over-detailed documentation is equally bad. Once, there was a team that was very accurate in terms of the documentation. They kept the documentation very low-level, documented every detail, including SQL statements, to illustrate how the business function is implemented. They believed the more documentation they produce, the better...until things started to change. Updating extremely detailed documentation is pain, and since people do not like pains, the updates will eventually always be skipped, so what the team ends up with, is the outdated documentation.

On the other hand, many times have we been presented with the documentation that looked like this:

Documenting obvious things without any added value is wasting time. Describe a "Search Flights" button like "This button searches for flights" is not rational as it does not have any benefits for the reader. Documenting should always be balancing between the amount of information that provides the best value and the effort needed to create it and maintain it. In the next part, it will be described what types of information are beneficial and is therefore recommended to include it in the documentation.

Documentation Templates

A lot of teams try to unify the documentation outputs by prescribing what must be documented and how. This is not the right approach. Different activities require different information and forcing analysts to always write use cases, for example, implies the project ends up having a lot of artifacts that do not provide any value.

REMEMBER

One size doesn't fit all. You should always tailor the form and amount of the documentation to the given situation and audience.

Inconsistencies and Duplications

It is essential to create quality and accurate documentation that has a decent level of detail and is continuously updated. On top of that, there are additional attributes that support its readability and enable its easy maintenance. Namely, it is making the information coherent, keeping the documentation artifacts consistent, and not duplicating information. Not meeting these requirements results in the following symptoms.

Information sprinkled throughout various documents

Use case descriptions in Word documents, decision tables in the linked Excel sheet, algorithms described using activity diagrams stored in the CASE tool. Even an average-sized project requires using multiple techniques and tools producing various artifacts. However, the information should always be stored in one place, interconnected, and easy to find. Only this way, is it possible to comfortably navigate between artifacts and search in all materials with a single query.

Information stored in many different places

Duplicated information is frustrating for two reasons. First, if the information is stored in many different places, each change must be reflected in all of them. Second, if all occurrences have not been identified, different contradictory versions of single information could exist. It is then hard to find out which version is valid.

Inconsistent analysis outputs

Producing consistent outputs does not mean filling templates or creating a fixed set of artifacts for every analytical activity. Consistency in this context means unifying descriptions of all solutions or enterprise components of the same type and storing them in a similar documentation structure. It is then easy to ensure that all process descriptions include all essential information the users expect and that the readers could find the process by the standard name within the standard structure.

Incoherence

Once, we saw a team that created a screen specification that consisted of a wireframe inserted in the Word document, a list of its elements in an Excel sheet, and a list of user interface events in the form of a diagram in Visio. It was then really frustrating to need to open all three sources and put the information together to learn how the screen is supposed to look and work. Additionally, the individual parts were not labeled with an identifier, so finding the behavior of the "Save" required going through the whole list in the Excel sheet.
If it were done with the coherence in mind, all the information would be included in the screen specification or at least interconnected using identifiers. Coherence in this context means storing all related information in the single and predictable place.

Text-only Documentation

Information can be stored in many forms, from a couple of sentences to a complex diagrams hierarchy. The task for a good analyst is to always choose the form which is most suitable for the given information and the intended audience. In some cases, several bullet points will do the job, but the text is not the best technique for describing all aspects of the solution. Following example depicts a textual specification of the identified business rules:

`" Discounts:

• If it is United Airlines and Paypal or Visa is used, the customer gets 2% discount
• If it is United Airlines and Mastercard is used, the customer gets 1.9% discount
• If it is American Airlines and Paypal is used, and at least 3 tickets are selected, the customer gets 1% discount
• If it is American Airlines and Paypal is used, and no luggage is selected, the customer gets 1% discount
• If it is American Airlines and the departure date is 24/12, the customer gets a negative bonus for -2% discount
  `"

Simple textual statements presented above are very easy to create, and it is also how most internet tutorials present the business rules. However, as it could be seen from the example, the simple text is not suitable for more complex rules as such specification becomes cluttered and not easy to read. The specification is unnecessarily long, and finding an individual piece of information is hard. Below the same information is presented using a decision table, and it is up to everybody to evaluate which approach is more useful:

It is very tempting to create text-only specifications. It is straightforward to start with it since no modeling skills are required, and all that is needed is a notepad. The analyst just opens any text editor, and in a few minutes, the process description is born. However, this approach does not scale. The text description cannot handle the growing complexity. It is ineffective in modeling conditions, branches, or events, and the effort required to maintain it grows with the increasing complexity.

Mixing Abstractions

The following example describes the steps a customer needs to take to buy plane tickets using the Cheap Flights website:

`"

1. Customer visits the website and selects "Buy tickets" in the dropdown menu ...
2. System searches for the tickets according to the criteria provided in the search form
   • System searches for the United Airlines tickets by calling service https://united.com/api/getTickets using GET method
   • System searches for American Airlines tickets by calling service https://aa.com/tickets using GET method
   • The connection is secured using HTTPS protocol ...
3. After the tickets are purchased, they are stored in the database in the table plane_ticket
   • Implementation remark: Table "provider" doesn't have a primary key `"

The problem with this description is that it is not clear what its purpose is. It mixes different perspectives: it defines the process, it describes the user interface details and even includes low-level implementation details such as URLs and integration specifics. As a result, it is hard to understand the business purpose as it is infested with implementation details, and at the same time it will be hard for developers to extract what they actually are supposed to implement. Such specification is not easy to read to anyone and the textual form makes it huge. Analyst's task is not just to obtain the information, but also to organize it the way it is understandable for various audiences. In most cases, this means starting with a high-level technology-independent description and only then adding more layers providing other perspectives, and describing additional details.

Tell me Why!

The Swinx company provides e-commerce solutions to big customers, and their flagship AeroEshop is currently operated by the 5 large e-shops. One day a really angry senior Swinx manger approaches an AeroShop product manager yelling at him why the PayPal payments for the second-biggest customer stopped working after the latest release.
The problem is that each customer installation has a dedicated analyst, and the guy responsible for this particular customer left the company after the concerned release, so there is nobody to ask. Luckily, a high-level description of the change was found in the shared folder. It clearly states that the customer really requested to remove PayPal payments, so the application works according to the requirements, at least. However, it is not included who initiated the change and why it was needed.

After two days of frustration on all sides, the requestor was identified, and it was clarified that the client decided to stop offering this payment method for internal reasons. The reasons were not communicated to the vendor, and the whole requirement was obviously not discussed with the senior managers at the customer's side either. If only the vendor had a list of change requests complemented with the reasons that triggered the change. Sometimes even the most precise specification is useless if it is not clear why the whole thing was implemented.

Missing Audit of Changes

Even if the team is instructed and understands what information to document, nobody is perfect, and some information is still going to miss. If the information is not included, the only possibility is to ask. And to be honest, is there anything more frustrating than having nobody to ask? To quickly find the most appropriate person, documentation changes should be audited.

Creating Documentation in Word Processor

Most analysts are very likely to have encountered this situation:

• The system specification is quite well written and is stored on a shared disc
• Unfortunately, it is written in Word: included diagrams are of bad quality, they do not fit on the screen correctly and navigating in the document is inconvenient since cross-references are mostly broken
• Searching is also clumsy as the specification is separated into many documents: one describes user interface, other deals with integrations and another specifies referenced business rules
• The fragmentation of the information also makes people pull their hair as to construct the whole picture, multiple documents located on different locations must be used

But still could be worse... The hell comes when such word processor documentation is also used as a collaboration tool. Editing documents and collaborating on them with another 3 analysts becomes a mess very quickly. After a couple of document roundtrips, nobody knows which version is the newest and who modified what. The problem might be partly minimized by using online office tools or an enterprise wiki software, which rapidly improves the collaboration.

Models Without Descriptions

Replacing textual descriptions with visual models when appropriate, is a great achievement. Unfortunately, even the visual specifications may be a source of frustration if they are not created with good practices in mind. Models are mainly created to visually describe complex aspects which would otherwise be very hard to describe using text. However, very few models are complete when including just the visual part. Most of them need to be complemented with metadata which specifies the visual elements of the model. That implies, if the model does not contain the information required by it to be completed, it is only partially usable.

Example 1

The following diagram depicts how customer's contacts are stored in the system. It could be learned from the diagram that each customer has two different contacts:

The question is, why it is modeled this way. Why are there specifically two contacts? Is it important that the model includes two separate contacts instead of a collection of contacts? Neither of these questions can be answered with just the diagram so it should be complemented with some text descriptions:

Now it is clear that each customer has one primary contact and one secondary contact. Perfect. Or not? What does it actually mean a primary contact, and how does it differ from the secondary contact?

Superb, now it's clear. Remember that models are not just about the symbols and lines. The semantics is equally important.

Example 2

The next diagram describes the logic behind entering and storing contact in the system:

There is nothing wrong with the diagram. It clearly states how the system should work, and it is unambiguous. The problem is its aim is to serve as an input for developers, and as such, it is not sufficient. How does the correct number look like? Where the number should be stored? Etc.

Well, this is better. If analysts spend their time creating a diagram, they should always decide its purpose and audience and continuously evaluate whether it serves the purpose and adds value to the audience.

This Should Not Frustrate Anybody, it is Life

The frustrations listed in the previous section are usually caused by analysts who are inexperienced, uneducated, or even just lazy. Eliminating these factors will naturally help also eliminate the imperfections which cause the frustrations. But there are also things in analyst's life which might look frustrating, yet they are natural, will always be here and instead of fighting them, it is sufficient to be prepared for them.

Changing Requirements

Software teams try hard to stop requirements from changing because each modification of what the solution should do usually means rework. But in fact, changing requirements are a sign that somebody thinks about the solution and is interested in it, which is actually good news. Another important aspect is that if stakeholders decide to alter what the solution should be capable of, they also say that the expected value changes. How could you then deliver value to the business if you insist on the old invalid requirements? After decades of fighting, teams realized that this battle cannot be won, and instead, they started taking it as a natural thing which became one of the core principles of the agile manifesto:

Responding to change over following a plan

Many people complain that they hate documentation because the requirements change so fast that it is hard to keep everything up to date and consistent. We think that it is just about the selected approach and the tools used, which together could enable teams to be prepared for the changing requirements. Here we present basic practices which are elaborated more in the next part of Effective Analysis:

• Document stable things
  • This practice helps minimize the documentation rework
• Document general things, not details
  • General things do not change that often, so the rework is less probable
• Avoid duplication and store information in one place only
  • Rework and maintenance is easier when duplications are minimized
• Do not mix different levels of detail
  • Good structure helps to identify places to be changed when rework is necessary
• Apply automation
  • Automatically generated documentation will save time

Not 100% Perfect Documentation

Missing documentation, outdated documentation, and documentation, which is impossible to read or modify, is frustrating. On the other hand, creating documentation is not the primary goal, and since it takes time that could be spent to actually build something, insisting on perfect documentation is not reasonable.

I can tolerate a map that is missing one or two streets but I can't tolerate one that is missing three quarters of the streets in my town.

-- Scott Ambler

It is obviously acceptable if the documentation does not state what the default sorting of the client list is or if the button is labeled "Save Customer" instead of "Save Contact." It is problematic when it lacks the summary of what is actually the business purpose of the button, or where it loads the data from.

Prevent Frustration

It should be in each person's interest to not frustrate others, both the teammates or those who will be using or supporting the created solution. This means to document things in decent quality, which will support not only the primary goal to deliver the solution, but also the secondary goal to enable next effort.

In the following part of Effective Analysis, we are going to present practices and techniques which help analyze and document solutions in a more systematic way, contribute to preventing frustration, and will make teams more effective.