Effective Analysis and Documentation

Effective Documentation

Producing quality documentation that provides value and is easy to read and easy to maintain presents a nontrivial challenge. This chapter summarizes principles and practices that support these attributes by applying simple, lightweight and iterative techniques and approaches.

1. Document General Concepts

Every documentation, be it the analysis or the post-release, is always inaccurate, since it is just a simplified model of reality. But is it a problem? Documentation reflecting the reality 1:1 would be great, but it would also be unmanageable as updating it every time some tiny detail changes would not be realistic. The general concepts, on the other hand, don't change that often. They serve as an information hub that redirects the reader to more detailed resources if needed, which also makes them great for introducing new team members to the project.

Overviews are very useful and easier to manage, details are only sometimes useful and difficult to manage.

The more is not always better. Maintenance of the very detailed documentation represents a significant overhead that must be justified, no matter if we are talking about the pre-release or post-release documentation. It is safer to document just the general things and include the details only if it justifiable and the information is stable.

2. Document Stable Things

During analysis and development, information frequently changes as more facts are being discovered and clarified. With the increasing adoption of agile approaches, the information turbulences during development are even more common, and what is more, they are welcome. But this also implies the need to change the way we analyze and document solutions. It is ineffective to document details, create perfect models, or write formal specifications if they are likely to change soon. Instead, it is reasonable to wait and document just what is yet stable enough so that the unnecessary rework will be avoided.

3. Iterate

Complex problems cannot be analyzed in one go and are instead broken down into smaller chunks and analyzed iteratively from the high-level to details. The same approach applies to documentation. Documentation is never perfect the first time and is usually developed over time. It is continuously revisited and iteratively improved until it is of decent quality.

4. Document Rationale

Documentation is primarily focused on capturing What and How - what organizational components we have, what their capabilities are, and how they internally work. But in most cases, this is not enough. Unless the documentation includes the reasons why things are the way they are, the information is not trustworthy for readers. They will ask for justification, such as who approved the design, where this information comes from, etc. As a result, it is equally important to document also the Why. We elaborate on this topic in the separate practice here.

5. Document With a Purpose

Creating documentation comes with a commitment. Each time you document something, no matter if it is a process, system, or a low-level algorithm, you publish an artifact that you guarantee to be reasonable, correct, and of a decent quality. Fulfilling this commitment takes time. That is why you should always ask first what is the purpose of the documentation you are going to produce, whether it will provide some value and whether it is really needed. Don't create a sequence diagram for each use case just because your team leader instructed you to do so when you are sure the diagram will not bring any benefit. Documenting must always have a clear purpose and must provide value, which is higher than the price paid for creating and maintaining it.

Below we list situations in which creating documentation is justifiable:

  1. To analyze something Analysts, SW architects, developers, and others, they all need to analyze or design aspects of the solution before moving to implementation. For instance, it is hard to just sit down and implement a complex process without discussing it with stakeholders and designing it with developers. Creating a process model is a convenient way of verifying the design, and it will also serve as an input for developers.
  2. To document organizational capabilities It is a hard task to discover how the organization must change to meet the business needs without the knowledge of what the organization is currently capable of. It is not possible to find the best solution without understanding what the company currently has and what it currently can. Each organization should have accurate and up to date documentation of its processes, systems, guidelines, rules, or people.
  3. To define contracts Communication between two entities is usually done through a formal interface. Be it waiting for an external sub-process or calling an external system, a fixed contract is needed so that both sides understand their parts within the relationship and the way of communication. Since the contract is binding, it is convenient to document it and share the specification with all parties involved.
  4. To conform with regulations The organization may also be required to create specific documentation to prove it has been following specified rules. It may be to prove to its customers that the solution meets agreed requirements or to confirm that the company conforms with the regulations issued by the government or other third-party entity. Since the documentation is obligatory, the organization has no other choice than to create it, but the team should always verify first whether the regulation is still valid to avoid unnecessary work.
  5. To communicate Communication through exchanging documents should never be preferred to personal communication as personal communication will always be much more effective. Requirements should be reviewed and verified in a meeting, not via commenting and exchanging specifications. Nevertheless, face-to-face communication is not always possible. Business stakeholders may not be available at the given time, communication across time zones is complicated, and sometimes the formal confirmation is required. As a result, documents are still a valid way of communication in specific cases, yet it is neither preferred nor recommended.

While it is justifiable to create "a document" in cases presented above, in the following situations, it should be seriously considered whether the documentation is really the best possible approach:

  1. Documentation is ordered If the team is ordered to create some type of documentation (there is a guideline, or a manager said so), it should ask if the guidelines are still valid, who particularly is going to use the document and whether creating it makes sense at all.
  2. Documentation is a custom Many teams create documentation just because they were told to do so in the past, so they continue to do it even though there is currently no legitimate reason for it.
  3. To prove productivity Some teams produce a lot of unnecessary documentation just to prove to managers or customers that they have been working hard. The progress should be demonstrated by a working solution, not by models and documents.
  4. To freeze requirements Teams working in the waterfall fashion create a "requirements document", make the customer sign it off and then try hard to deliver exactly what has been approved. However, fixing the scope by freezing requirements has proved not to be working. Good relationships with stakeholders, collaboration, and following the common goal through iterative analysis and development are far more effective approach. Freezing requirements is very likely to turn against the team as the customer will change the requirements anyway. The team will then have trouble delivering the solution since the documentation always lacks some information, which will cause the delay.
  5. To communicate See point 5 in the previous list

6. Keep Documentation Simple

Because repetition is the mother of retention, let's remind it again: documentation is not the primary goal, its purpose is just to support teams in finding and implementing solutions to business needs. For this reason, documentation should be as simple and straightforward as possible, while still providing value and meeting the described quality attributes.

  1. Take the iterative approach, create the most essential documentation, review it with your audience and add details only if it is required
  2. Use lightweight techniques: simple statements, bullet lists, sketches, basic use cases, etc.
  3. Don't be afraid of simple analysis and development documentation. Projects usually do not fail because of simple documentation, but we have seen a lot of projects fail because of wasting time on comprehensive specifications instead of focusing on delivering the solution.
  4. Avoid duplications

7. Reviewed and Keep Up-to-date

If the goal is to keep the high-quality standard of the documentation, it is inevitable to put some review process in place. It is a tough task to write ambiguous documentation that will be clear for all readers and to synchronize the look and feel of the documentation across the organization. Letting somebody have a look at the produced documentation is beneficial for identifying ambiguities and evaluating the overall documentation quality. It is especially important for the as-is documentation whose lifespan will be a couple of years, so the effort put to review will pay off.

8. Well-Arranged

All the effort put into making quality documentation may be wasted if it is poorly organized. It is necessary to structure the documentation coherently and divide it into logical parts so that it is easy to navigate within it. The concrete structure depends on the needs of the particular project or organization, we could only provide you with examples of the analysis documentation and the post-release documentation.

It is also crucial to have a clear "starting point" for each logical component. Its purpose is to provide an overview serving as an entry point from where the reader is referred to more detailed parts so that the information is "layered" and the reader is not overwhelmed with details right from the beginning.

9. Structured and Interconnected

Documentation is not a monolith. It consists of several layers which allow looking at the subject from different perspectives. The layers could be - horizontal and vertical.

To maintain good readability and navigability within the documentation, links between the layers must be created and maintained. It should be easy to navigate from one aspect to another and from the high-level description to more detailed views.

10. Unified

Team members come and go, documentation is handed over from one person to another, and it is shared among various parties. Besides, it is usually necessary to read multiple documentation to understand the big picture. This is why documentation should be as much standardized and unified as possible.

11. Public and Easy to Edit

"A common mistake that I've seen architecture groups make is to put their diagrams on the walls within their work areas but not the work areas of the application developers."*

– Scott Ambler

The information included in the documentation is only beneficial when it is easily accessible by everyone interested. Nobody will review diagrams if they are stored in a complex modeling tool, which requires training just to open the diagram. Business stakeholders will not help identify bugs in the documentation unless it is presented to them in the form they are familiar with. Besides, documentation of all components must be accessible from a single place, so there is no need to search for the particular documentation, ask for credentials, etc. An example of such a solution is presented in Part III.