Analysis vs. Post-Release Documentation

Documentation is usually created for two reasons. It either describes the current state or specifies future changes. The reason to distinguish between these two documentation types is that they require different approaches.

The following schema shows both documentation types. The company decided to solve the need to catch up with its main competitor by implementing a new mobile app reservation system. The left part of the schema represents the analysis documentation, which describes the requirements and design of the system. The goal of this documentation is to provide enough information for the development team so they can implement it. On the right side, there is a description of the solution after it is released. This part will be used as a reference and will be beneficial for people who will be responsible for operating the application and extending it. Since both types of documentation serve different purposes, they do not look the same, as described in the following sections.

Analysis Documentation

Analysis documentation represents all information needed to implement a new solution. The form of the analysis documentation varies heavily, as each project is different, follows a different development approach, and is performed by different people with different skills. Therefore, there cannot be a single analysis documentation approach, and the team always needs to select the solution which best suits the needs of the project or the given situation.

This gives teams absolute freedom in choosing what types of artifacts they will produce, how detailed they will be, and when they will be created. Since their primary goal is to deliver the solution and not to produce documentation, the documentation should be as simple as possible while still providing all the necessary information to implement the solution. Any documentation beyond that is a potential waste of effort, as it is not guaranteed to be needed. Effective analysis documentation is hence the simplest, most minimalist, lightweight documentation that is sufficient to successfully deliver the solution under the given conditions.

The following list presents techniques that support the effectiveness of analysis documentation. We could call them lightweight or agile; the fact is that applying them helps analysts be more flexible and responsive to changes:

• Presenting information using bullet points instead of formal text (because people do not read long formal texts)
• Using whiteboards instead of formal presentations (because they support collaboration and can be changed quickly)
  • 
• Presenting working prototypes instead of going through heavyweight documentation (because the development team needs fast feedback)
• Using simple sketches or wireframes for screen modeling instead of perfect designs (because the screen is a model and the primary goal is the software, not the model)
  • 
• Using diagrams instead of models (see this section for more details)
  • 
• Using essential use cases, user stories, and other agile forms of requirements modeling techniques instead of formal requirements lists

The above techniques support analysis effectiveness by:

• avoiding creating comprehensive documentation which quickly becomes outdated and is often not used at all
• not wasting time producing perfect artifacts when just a quick sketch would also do the job
• promoting collaboration with stakeholders instead of reviewing specifications

Good analysis and design documentation must be just good and formal enough to enable the primary goal—the development of the solution. However, the team must also support the secondary goal, which is operating and extending the solution. This means that some of the temporary analysis artifacts will consequently become part of the permanent post-release documentation. So, if the development team concludes that it would be worth keeping a particular artifact in the post-release documentation, it waits until the artifact is stable enough. Then it describes it in a way that is suitable for including it in the post-release documentation (see next section).

Post-Release Documentation

The primary goal of analysis is to find the best solution that meets the business goals and to describe it in a way that enables implementation. Nothing more and nothing less; so as long as the analysis documentation fulfills this goal, its form and timing depend on the needs of the particular project and team.

But as previously mentioned, the lifecycle of the solution does not end with the release. Subsequently, someone must operate it, maintain it, extend it, or integrate it with other solutions, which all require a different type of documentation than the analysis. Besides, the team responsible for supporting the solution is usually different from the one that developed it, so before learning details, the team must first learn the big picture: where the solution fits in the overall enterprise architecture, what is its purpose, and how it integrates with the outside world.

During analysis, things are turbulent, everything changes frequently, and it does not make sense to create complex formal outputs. Aspects of the solution are regularly discussed with the stakeholders and within the team, so the knowledge is shared and does not need to be extensively documented. Post-release documentation is different. It will most likely be used months or even years after the release by people who were not part of the project. For this reason, it must first introduce the solution through a high-level overview and start with the basics to be understandable even for people who have never heard about the solution. It must also be very explicit. While there is always somebody to ask for clarification during analysis and development, these people may no longer be available during the maintenance phase. So if information is essential, it must be clearly understandable just from the documentation. For this reason, it should not use business or IT jargon without explanation, and it should not assume readers will read between the lines.

It is clear from the previous text that in contrast to analysis documentation, post-release documentation is more high-level, focuses on overviews and contexts, and is usually more explicit and "formal." Since it describes stable facts which are not likely to change often, it can afford to use more rigid and robust techniques, such as formal models, unified artifacts, or traceability. More robust documentation takes more time to create, but as there is little risk of frequent rework, it is safe to invest the time in exchange for quality and unified outputs.

By formal, more robust concepts, we mean:

1. Unified form of documentation of the common artifacts

In most cases, post-release documentation describes multiple enterprise components, such as systems, business processes, or organizational structure. Readers usually need to go through various documents to get the whole picture. To make readers' lives easier, it is convenient to standardize the form of documentation for different components so that switching between them is smoother. In an ideal world, the format of the Screen 1 description should be very similar to the documentation of Screen 2.

2. Modeling instead of diagramming

Analysis documentation changes frequently, and its parts may be added or removed on the fly. This is why simple diagrams are preferred to formal models until the information is stable.
On the contrary, at the time of writing post-release documentation, all aspects of the solution have already been identified, described, and even implemented, so it is then safe to refer to concrete enterprise components such as processes, systems, or their elements:

• Clicking on a button displays screen SCR-12
• Data is loaded using service Get Customers() from the CRM system
• Use case step triggers process PROC-15

3. Capturing traceability between individual components

The primary goal of documentation is to capture how individual enterprise components work. This is what most teams document, and it is usually sufficient for solving incidents or supporting the solution. However, such documentation cannot help with identifying dependencies and the impacts of changes, so it is of little use for teams extending the solutions. It cannot show relationships between the components and answer questions such as "What systems and parties are involved in this business process?" or "What systems access this database table?".

4. Describing real capabilities instead of abstract concepts

Development specifications do not have to be perfect as long as they do not rapidly decrease the effectiveness of the development team. If the development team works closely together and cooperates effectively, the specifications might be a bit ambiguous because developers have a chance to clarify things quickly.
For example, if all team members know that there is a single privilege that controls the visibility of administrator tools, the following statement is fine: "Button is visible if the user is an administrator."

Post-release documentation is different, though. The supporting team has no idea what "is an administrator" means. So if they are approached by a user complaining the button is not visible to them, they need to know the concrete privilege so that they can check the user's settings.

• "Button is visible if the user is an administrator" vs. "Button is visible if the user has the ADM privilege."*

5. Complying with documentation quality rules

A serious problem with documentation is that people do not trust it, and the problem gets bigger as the documentation becomes more complex. To make documentation trustworthy, the organization must set up obligatory rules for creating and maintaining documentation of its assets. Employees will only use the documentation if they know there is a process behind it, which controls its quality and guarantees it is reviewed and up to date.

Organizations must build up obligatory rules for creating and maintaining documentation of its assets. There should be a process in place stating what, when, and by whom should be documented and who is responsible for particular parts of the documentation.

The credibility of the documentation is also supported by its appearance: unified professional templates standardized across the organization should be used, correct grammar and formatting should be applied, and a neat visual style also helps improve its perception.

Governors vs. Invaders

When it comes to consuming post-release documentation, there are two different camps, both seeing it from different perspectives as they have completely different interests.

The first group are the people who are responsible for maintaining the legacy systems—the governors. They use the documentation on a daily basis, so it is in their own interest to ensure it is understandable and correct, as it may influence their day-to-day performance and comfort. The systems and their documentation are their land; it is everything they have, and they have learned how to govern it and protect it from any intruders who would like to do something wrong to it. They plan each change very carefully, as each unconsidered change to their land can impact their lives. They do a great job keeping the systems running, and they often have the best knowledge of how the systems work. The downside is that since governors know the systems from A to Z, they have become used to living with all imperfections, including the way the systems are documented. They have learned the structure and rules of the documentation by heart, so they do not have trouble finding any information no matter how the documentation looks. Governors do not understand why it is so hard for other people to find the right information when it is stated in their documentation. Governors should be trained on how to structure documentation, how to model information systems, and they should try to standardize the documentation with governors of other systems so that it is easy to change the camp and start governing another camp very quickly.

The complete opposite of governors are invaders. They do not care about existing camps or villages; they were ordered to invade the territory and build a wooden cottage to test whether it is actually possible to live there. The deadline is in three weeks, so there is no time to plan. Invaders are teams asked to quickly build a concept or a prototype. The deadline and features have priority, agile development is an alibi for not documenting anything, and in the end, the company ends up having an undocumented prototype that survives the next couple of years in production anyway. The problem is that invaders conquer the land and leave, but governors will have to stay and maintain it.
The advice here is to make documenting an integral part of development, preferably in collaboration with governors to meet their needs. This includes documenting at least the high-level overview of the system's business purpose, the IT architecture, and the key decisions behind the project so that governors' lives are easier when they take over the territory.