Lean documentation tooling

Created on 2018-03-21 12:55

Published on 2018-03-23 07:33

In order to get a job well done the tools should be carefully chosen. However tools have to chosen based on the size of the job one's trying to get done. If the job is as massive as digging the Panama channel, a shovel won't help much and also for a flower pot an excavator would be an overkill.

For a software project there are several kind of tools that are used to build and document the project. One important category here is communication and collaboration tools. The typical enterprise collaboration tools is Microsoft Sharepoint or something equivalent, probably Jira. Many of the requirements architecture, design and deployment artifacts are shared between team members and with stakeholders using Sharepoint as a repository for documents, spreadsheets, diagrams, presentations. However the process of editing these artifacts requires a check-out of the file, updating it with some items and then checking it back so that other people can see the changes. This raises a problem because concurrent modifications to a file are hard to do as it involves some kind of merge at document level. Moreover, there are some tools that are not really designed to work in this manner and they have their own internal versioning mechanism (e.g. Sparx Enterprise Architect that is using a database in order to offer some concurrent access to the same model). Also you might need to have the same tool installed at every member of the project in order to effectively be able to contribute with changes so more licenses might hence the costs would rise up.

What I find interesting here would be to increase the collaboration value and lower the total cost of tooling. One excellent example is Wikipedia engine (Mediawiki) that permits thousands of simultaneous users that can read and change the content concurrently. This is also an interesting enterprise approach inside a team because a wiki engine works as a version control for the content it holds. Instead of adding word files it would be easier just to edit some wiki pages, where the edits and merges happen concurrently. Security rules and workflows can be enforced on a wiki. Sharepoint permits the creation of wiki pages so it enables this kind of collaboration. As the information is less constrained in long check-out, modify, check-in cycles it tends to stay more up to date.

How to treat diagrams in this case? In fact diagrams can be treated the same as other textual information. Tools like PlantUML can be used to render diagrams in real time starting from text representations. The text representations of diagrams can be written by any engineer or even extracted from existing code or infrastructure. This information would be quite up to date with the current state of the project and would benefit from all the advantages mentioned above: versioning, merges, etc. There can be even a reverse flow where diagrams can be obtained from code or deployed servers and containers thus documenting live state of systems.

When the content should be given outside the team it can be exported to PDF or another format keeping or even enhancing the format and appearance of the document. For an organization that embraces a devops culture this approach is inline with their philosophy. The documentation and collaboration is part of the production pipeline, is always deliverable and versioned. It can be integrated both in the CI/CD tools as well in the tools (extensions for Eclipse, Idea and Visual Studio are readily available).

The cost for such an approach might be very well close to zero especially when wikis or similar solutions are already in the company. This is not mutually exclusive with engineering solutions as Rational Rose, Enterprise Architect or even Visio. The latter are extraordinary tools with a broader scope than mere collaboration and information sharing as they enable model based development, code generation and other high end features. A lean approach would reduce a high upfront investment in tools and use the expensive licenses on a more rational way, the funds saved this way might be used to bring more value to the product.