Introducing Github Sync

Software architecture diagrams drift from reality over time

One of the biggest issues with diagrams within organizations is that it drifts over time from what it was originally made to describe. You make a diagram for a presentation, upload it to a central documents storage, where it becomes outdated in a week, but referenced and looked at for years.

This is something that we think a lot about at Terrastruct. How do you prevent documentation drifting from the implementation?

More processes, more labor

At one extreme, there’s strict enforcement. Set up a system where parts of a codebase are tied to documentation. Upon a pull request for changes to the code, the changes must include changes to the referenced documentation. If no details need to be updated, the “Last reviewed” is bumped up to the current date. The effect is that documentation becomes an equally important part of the changeset as tests are.

There’s a case for stringent processes, but it undoubtedly slows down velocity. You want that type of slow, checklist-orientated, careful approach for delicate parts of your codebase, like the payments flow, or infrastructure configurations.

For the other 95% of your codebase, however, it’s as unnecessary as 100% test coverage.

Tests typically stay up-to-date because they’re run in the cycle of continuous deployment. Can diagrams be a part of that cycle? Is there a way to detect that a change has made a diagram “break”? That way, instead of manually reviewing documentation for each PR, you are prevented from merging if a breakage is detected.

The most straightforward implementation of such a system is to tie tests to diagrams. When you draw a diagram, you also include tests that exercise what they describe. If one of those tests break, it means the diagram has broken.

These are interesting ideas for organizations to make documentation a first-class priority, but it’s still added labor and they all come with their own drawbacks.

The simplest solution

The simplest approach to preventing diagram drift is this: look at it. Don’t tuck it away into some nested corner of Confluence. Backlink to it from other docs. Build upon and reuse them in future presentations if the subject matter is closely related. When docs get looked at frequently, mistakes are fixed without any enforcement.

Github Sync

Terrastruct’s latest feature lets you automatically sync diagrams to a Github repository. Every hour, if there are changes to your diagram, a push is made by our bot. Terrastruct’s diagrams are unique in that they’re multi-dimensional instead of static images, and we’ve made sure to preserve that in the Github repository. Each layer is encapsulated with a nested directory, and the README includes the diagrams for that layer, as well as the scenarios defined in each layer.

Click here to see an example of an automatically generated repository.

Privacy-first

We treat customer data and privacy with the utmost respect. We don’t ask for names or any other information aside from an email (for password recovery and login identifier) when you register. And for this feature, we opted not to use a Github app that would require access to all your repositories. As a principle, we want the least amount of privilege to do what we need. So, with Terrastruct’s Github sync, you create a new repository, and invite our bot as a collaborator to only that repository.

That’s all you need to do. Subsequent changes are then pushed to that repository with the timestamp, and arranged the way you intended to.

Syncing to Github allows developers in your organization to see the diagram in a familiar place that they frequently visit. You have the option of colocating it even closer to your implementation by including the repository as a submodule.

Now, if a developer wants to see the latest version of a diagram, they don’t even have to leave their command line. Integrating with your existing tools and apps is a big priority for us, and there’s more to come in the near future.