The Documentation of Things is one of the most boring, tedious tasks known to IT projects. It's also one of the most time consuming - and critical - collections of information for project success. So why do we keep doing it manually?

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?

Our most favorite product these days is GitBook. Not only does it combine Markdown and git together, but does so in a way that makes Confluence look slow and clunky in comparison. GitBook offers a rich API experience, customer engagement, Google Analytics, and Slack integration. The pricing is reasonable, though it could use a price point between the Free and Team edition. We're going to start migrating our old technical documentation projects there, and do a separate writeup of our experiences - stay tuned!

Need help with technical writing, documentation, or even copyright for websites or sales? Contact us today for a free quote,and learn how you can improve quality through a neutral outsider AND save some money in the process!