On the Documentation of Things (DoT)

Wednesday, September 11, 2019

On the Documentation of Things (DoT)

I just published an article on LinkedIn where I wrote a somewhat tongue-in-cheek letter to Atlassian, asking them to use their amazing Confluence platform to come up with a way to use a combination of micro frontends, webhooks and an "embeddable document" type to try and help solve the task around getting a handle on what I call the Documentation of Things.

The Documentation of Things is one of the most common tasks - when performing an IT project, significant effort is made collecting systems information around the scope of the project itself. As additional platforms, components, and systems are added, the complexity grows in scope, and is multiplied by the number of environments that require such documentation (test, QA, etc.). It becomes an all-out effort for team members to nail down details and nuances that are known and used by the systems themselves. So why don't we automate it?

There myriad approaches that can be taken with this. Using the micro frontends model, one could come up with a standard where, with a request to a URL with a /doc endpoint, one retrieves a message payload containing a combination of metadata and raw HTML/JSON/XML content to be used by the requestor in order to obtain the desired information around the configuration of any particular thing, whether specific to an application or to the system as a whole, configurable through the specification of the request itself.

Given the nature of the complexity of such an architecture, it would therefore be easier for product vendors such as Atlassian to create - at the very least - some sort of model for accomodating these requirements. I think the ones I threw in there are at least a good start, so it's worth a shot at throwing some ideas at the company to see how they respond to the idea.

While they're pondering it, however, if one were interested in building a competing product to Confluence, may we recommend a high performance database library that really is built for such ventures?