Schema Management is Documentation, too

So why do we do documentation, again?

Well... we do it to explain the implicit.

Any codebase written for a system build or interpreted for a technical audience comes from a data type. So to large degree, documentation is a logical byproduct of any given codebase. Moreover, such communication is the supportive fabric that holds together engineer and information (ideally, captivate former to latter).

After reading a thought-provoking article titled "Discovering an Implicit Schema in JSON documents I played out an imaginary scenario in my head. What happens when engineers I work with get held up on their workflow when dealing with inexplicable markup? There might be some exaggeration to that thought but that's okay. The author of the article, Jordi Cabot, proposed a pre-development phase that consist of modeling and well-conceived discovery if such an issue reared its head.

One thing to note, as Cabot calls out, JSON is schema-less. That's a good thing because the format can be interpreted by multiple frameworks (e.g. Ruby, Django, etc.) without any heavy lifting. The business analyst within me nodded with satisfaction

Though confronting this chicken-or-egg approach sounds like a given, Cabot makes a pretty non-negotiable argument on modeling requirements, pre-development. This process is called domain modeling. Domain modeling is a common document/artifact that, like a skeleton key, lends itself to development methodologies as lightweight as Feature Driven Development to the more rigorous Test Driven Development.

In a previous post I journaled my exploration and discovery of automated documentation. Automation comes from a well-thoughtout ideation and planning, which goes hand-in-hand with domain modeling. Order and progress ensue, and all teams can potentially find happiness at the behest of well documented framework, including the business analyst within me.

Read the Jordi Cabot’s write-up here.