Published on 2018-06-29 20:57 (LinkedIn)
Documentation is key to designing and maintaining a well running solution. Be it technical design specifications, data flow diagrams, catalogs of metadata, and even code comments – all these written forms allow for sustaining engineering and communication among the development team. Heaven forbid if your star developer gets hit by the proverbial bus, lottery ticket or job offer, and your blueprints are not up to standard.
The nature of good technical documentation is to be living, evolving and conforming to the as-is and to-be state of the solution. Documentation should be produced before, during and after the development process. Whether you are working in an agile or waterfall process – there are tools and processes that can help.
At the inception of an analytics solution I create a solution blueprint diagram. Visio is an industry standard, but I prefer an open source graph editor called yEd. The tool allows for rapid design of architecture blueprints, ER diagrams and data models. The foundation of any graph data is its nodes and edges, in this case represented by an XML like language called graphml. The key elements of which can be imported / exported to Excel, Visio and even natively in SQL Server’s graph tables.
I keep the architectural blueprint under source control and update it throughout the development lifecycle. By doing this the team can track changes between branches and releases. Short on time? Take a picture of diagrams on a whiteboard and add it to source control. Need to collaborate on specs? Try OneNote on SharePoint or Microsoft Teams.
However, the architecture blueprints only tell half the story; the “before” or “expected” design. Static analysis and documentation tools describe the “after” or “actual”. Documentation can automatically be generated as part of build and deployment process available in mature application lifecycle management and DevOps processes. Code metrics, database metadata and code coverage help explain the intricacies of the solution on every versioned build of the solution.
Interested in yEd? Here's the 90 second demo: