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, according to our experience, still very popular despite it is quite old-fashioned and possess limited possibilities:

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

Other downsides of textual documentation stored in offline documents are 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 splintered into multiple documents
3. It is not possible to filter only relevant information. If the document includes use cases and user interface specifications, it cannot be easily separated.
4. Reusing information in different places means duplicating it. Information cannot be shared and modified from one place.
5. Referencing information is not straightforward
6. Versioning and access management is complicated

Documents in Cloud

As the online office tools (G Suite or Office 365), are becoming popular, they represent an alternative to the old-fashioned offline documents also in the field of documentation. On top of the features of the traditional office software, it adds the ability for multiple people to simultaneously contribute to the document, to track changes, better searching, and sharing documents via URL link. Nevertheless, the other disadvantages of the offline documents remain, such as including duplications, updating diagrams, or reusing information.

CASE Tool

Computer-aided software engineering (CASE) represents software tools which support specific tasks in the software development life-cycle. They aim to increase the quality of software development and maintenance by involving software and automation. The support takes place on multiple levels: IDE tools for developers, project management tools or modeling, or CASE tools for analysts and architects. From the perspective of analysis, architecture and documentation, we call a CASE every tool which allows users to build up 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 allows following the basic Effective Analysis principles very easily. All elements are unique, could be reused in multiple models without duplicating, and since they are all represented as entities in the database, it is straightforward to identify dependencies among them, perform searching, filter them or export them in various formats. CASE tool is not just a drawing tool, it gives meaning to the contained elements and relationships between them.

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

Wiki

Unlike Word documents, wikis were designed with collaboration in mind. They support versioning, audit, searching, or access control. One wiki page can represent a complete specification or could document just one artifact, such as a use case or screen. The documentation could be presented to stakeholders as is - in the form of wiki pages, or it could be exported to other formats easily. Even though wikis solve a lot of weaknesses of the traditional document-based specifications, they still share some critical imperfections. Information reuse is very limited, so the problem of duplicating information remains. Exporting data is impossible since everything is text, and the only traceability that could be created is between pages. Updating diagrams in the pages is hard because it must be first exported from the drawing tool and manually updated on 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 the team wants to model in the CASE tool, the individual diagrams must subsequently be imported to the wiki.