Documentation Approaches

This chapter describes the most common approaches to creating documentation and elaborates on their advantages and disadvantages.

Word Processor

Composing specifications using a word processor (Microsoft Word or similar) is, in our experience, still very popular despite being quite old-fashioned and having limited possibilities:

• Sharing is complicated (basically limited to passing documents around via email or using shared folders)
• Including and updating models in documents is clumsy
• Concurrent modification is not possible

Other downsides of storing textual documentation in offline documents include the following:

1. It is almost impossible to effectively track changes.
2. It is complicated to search across projects, systems, etc., as the documentation is fragmented into multiple documents.
3. It is not possible to filter out only relevant information. If a document includes use cases and user interface specifications, they cannot be easily separated.
4. Reusing information in different places means duplicating it. Information cannot be shared and updated from a single place.
5. Referencing information is not straightforward.
6. Versioning and access management are complicated.

Documents in Cloud

As online office tools (such as G Suite or Office 365) become more popular, they represent an alternative to old-fashioned offline documents in the field of documentation as well. On top of the features offered by traditional office software, they add the ability for multiple people to simultaneously contribute to a document, track changes, search more effectively, and share documents via a URL link. Nevertheless, the other disadvantages of offline documents remain, such as dealing with duplication, updating diagrams, or reusing information.

CASE Tool

Computer-aided software engineering (CASE) represents software tools that support specific tasks in the software development life cycle. They aim to increase the quality of software development and maintenance through software support and automation. This support takes place on multiple levels: IDE tools for developers, project management tools, or modeling and CASE tools for analysts and architects. From the perspective of analysis, architecture, and documentation, we consider a CASE tool to be any tool that allows users to build a repository of enterprise components, describe them using metadata, model relationships among them, and query this information to identify dependencies.

Storing all artifacts, requirements, and models in a single repository is a very convenient strategy that makes it very easy to follow the basic principles of Effective Analysis (https://www.effective-analysis.com/textbook/part-2/chapter-2/index.html). All elements are unique and can be reused in multiple models without duplication. Since they are all represented as entities in a database, it is straightforward to identify dependencies among them, search, filter them, or export them into various formats. A CASE tool is not just a drawing tool; it gives meaning to the components and the relationships between them.

Fascinated by the wide range of features, many teams have chosen a CASE tool as their main tool for producing and storing documentation. CASE tools are very effective at organizing data, manipulating data, and creating models, but they lack the features that analysts need most—editing text and presenting information to stakeholders. Analysts describe requirements, write use case scenarios, and specify business process steps, all of which involve writing and formatting a lot of text. Despite the fact that today's CASE tools allow editing elements and models in rich text format, it is still not straightforward to reference external resources, attach files, include images, etc.
Another problem is presenting this information to business people. Since a CASE tool is essentially a database, the information must be exported into a human-readable document. Even though CASE tools allow users to generate HTML or PDF documents based on a custom template, the exporting process is rarely straightforward, and the results are not always satisfactory. Furthermore, by generating offline documents from the CASE tool, organizations basically end up facing the exact same problems as if the documents had been created using a standard word processor.

Wiki

Unlike Word documents, wikis were designed with collaboration in mind. They support versioning, audits, searching, and access control. A single wiki page can represent a complete specification or document just one artifact, such as a use case or a screen. The documentation can be presented to stakeholders as is—in the form of wiki pages—or it can be easily exported to other formats. Even though wikis solve many weaknesses of traditional document-based specifications, they still share some critical shortcomings. Information reuse is very limited, so the problem of duplicating data remains. Exporting structured data is difficult because everything is text, and the only traceability that can be created is between individual pages. Updating diagrams on these pages is tedious because they must first be exported from the drawing tool and then manually uploaded to the wiki page. Although many wikis allow users to draw diagrams right in the tool using plugins, the result is only a drawing, not a model. If a team wants to model within a CASE tool, individual diagrams must subsequently be imported into the wiki.

![aa](https://www.effective-analysis.com/textbook/resources/doc-wiki