Documentation in the era of MCP
"Invisible" docs are good docs
Documentation shares a few characteristics with design. None is more poignant to me as the principle, "design is successful when it is invisible - when it is not noticed." The premise being that the goal of design is to enable the user in such a truly seamless way that they do not even notice how they are being enabled.
Although ease-of-use is reinforcing for us - we will choose what is easiest - it is rare that anyone who isn't a designer notices just how that ease was achieved; no friction, no investigation. Conversely, a hallmark of design failure is when it gets so immediately in the user's way that it becomes the only noticeable thing.
Technical documentation shares this quality: a frictionless, seamless experiences are what we all want, in most cases - to be able to realize our goal, without struggling to achieve it.
Good documentation achieves this level of "invisibility" in a few different ways, but the one I want to focus on right now is staying updated. It's a simple enough premise, but without sufficient automation pipelines in place, this goal is seldom achieved. Yet in the era of AI, this is inconceivable.
So how do we do it? Enter MCP.