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 they require a different approach.

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 would be able to 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 documentations serve different purposes they do not look the same as it is described in the following sections.

Analysis Documentation

Analysis documentation represents all information that is needed to implement a new solution. The form of the analysis documentation varies heavily, as each project is different, follows 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 the 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 needed to implement the solution. Any documentation beyond that is a potential waste of effort, as it is not guaranteed it will be needed. Effective analysis documentation is hence the simplest, most minimalist, light-weight 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 light-weight 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 texts (because people do not read long formal texts)
Using whiteboards instead formal presentations (because they support collaboration and could be changed quickly)
Presenting working prototypes instead of going through heavy-weight documentations (because 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 effectivity 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 into the post-release documentation (see next section).

Post-Release Documentation

The primary goal of the analysis is to find the best solution which 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, somebody 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 who 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. The 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 the 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 to read between the lines.

It is clear from the previous text that in contrast to the analysis documentation, the post-release documentation is more high-level, focuses on overviews and contexts and is usually more explicit and "formal". Since it describes the stable facts which are not likely to change much 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 just a little risk of frequent rework associated, it is safe to invest the time in exchange for the quality and unified outputs.

By formal, more robust concepts we mean:

1. Unified form of documentation of the common artifacts

In most cases, the post-release documentation describes multiple enterprise components, such as systems, business processes or organizational structure. Readers usually need to go through various documentations to get the whole picture. To make readers' lives easier, it is convenient to standardize the form of documentation of different components so that switching between them would be 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 really stable.
On the contrary, at the time of writing the post-release documentation, all aspects of the solution have already been identified, described and even implemented, so it is then safe to refer to the 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 the 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 impacts of changes, so it is of little use for teams extending the solutions. It cannot show relationships between the components and answering questions such as "What systems and parties are involved in this business process?" or "What systems do access this database table?".

4. Describing real capabilities instead of abstract concepts

Development specification does not have to be perfect as long as it does not rapidly decrease the effectiveness of the development team. If the development team works closely together and cooperate effectively, the specifications might be a bit ambiguous, because developers have a chance to clarify the 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 administrator".

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

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

5. Complying with the documentation quality rules

The serious problem of documentation is that people don't trust it, and the problem gets bigger as the documentation becomes more complex. To make the documentation trustworthy, the organization must set up obligatory rules for creating and maintaining documentation of their assets. Employees will only use the documentation if they know there is a process behind the documentation, 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 their assets and 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 how it looks: unified professional templates standardized across the organization should be used, the correct grammar and correct formatting should be applied and a neat visual style also helps to 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 is 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 got used to living with all imperfections, including the way the systems are documented. They learned the structure and rules of the documentation by heart, so they don't have trouble finding any information no matter how the documentation looks like. Governors don't 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 the 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 is invaders. They don't care about existing camps or villages, they were ordered to invade the territory and build up a wooden cottage house to test whether it is actually possible to live in the territory. The deadline is in 3 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 the 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 the 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.