When it comes to documenting things (e.g code, business processes, [[Enterprise Architecture]]), all possible approaches exist on a spectrum whose far ends are "free-form" and "stringently adhering to a well-formed metamodel". ![[Pasted image 20241007175644.png]] | Type | Pros | Cons | | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Free-form | Expressive & easy to read, easy to write | Difficult to scale & maintain, subjective to [[Documentation Rot\|rot]], each one is different | | Model-based | Drillable, pivotable, scalable, consistent | Difficult to interact with, tedious, requires specialized knowledge | The [[histogram]] of approaches I've come across in research and in the wild would draw an inverted bell curve across this spectrum. ![[IMG_1376.jpeg]] There seems to be a gap in the middle. Something that's more structured than free-form "anything goes" documentation, but something more naturalistic than the esoteric [[Domain Specific Language]] used by whatever modeling tool. Such a tool would enable [[Modeling as a Knowledge Base]], and sit on the line between machine & human readable. Such a tool is (probably) not possible for general use cases. The only cases I can think of that slot in the middle would be very limited domain or niche applications. Things like IMDB, or perhaps a well-made Jira [[hierarchy]] _could_ be sort of in middle. Perhaps an argument could be made for [[Code Auto-Documentation]] sitting somewhere in the middle. # Bridging the Gap It seems like you could bridge this gap only by starting from one end and applying energy and effort to "buy back" the benefits available on the other side of the spectrum. ## Scenario 1 Start with free form documentation. Develop common templates. **Expend effort** to figure out how to make features of your chosen toolset to try to make structures and consistency emerge from the squishy mass of your free-form documentation. ## Scenario 2 Start with a pre-built modeling language (eg [[UAF]], [[Archimate]], or plain old [[UML]]) then **expend effort** to make the models (or model derivatives) more human-readable/layperson-friendly. Either way, you are expending effort to "make up for" the deficiencies inherent in the chosen approach, and the toolset will ultimately not help you sustain the modifications you're making to its natural state. **** ## Source - Self ## Related - [[Modeling as a Knowledge Base]] - [[There is Tension Between Documentation and Being Agile]] - [[Decay is More Likely Without Strong Containment]]