Need Documentation to Teach What Questions to Ask
MCP-enabled documentation disproportionately benefits experienced developers because junior developers don't know what questions to ask.
Take Control Of Your Signals — Become a Naftiko Design Partner Today!
Persona Story:
Nico, the partner/integration AI lead, is trying to enable a broad spectrum of developers to integrate with APIs via MCP-enabled documentation, but realizes junior developers can’t effectively use queryable docs because they don’t know what to ask.
Problem Context
- Documentation is increasingly machine-accessible and queryable via MCP servers
- Current doc strategies assume developers already have the mental model to form good questions
- Junior developers “don’t know what they don’t know”
Problem Impact
- MCP-enabled documentation disproportionately benefits experienced developers
- Integration quality suffers as developers miss critical constraints
- Support burden grows as the same foundational questions repeat across teams
Naftiko Today
- Agent Skills group MCP tools into business-level capabilities with descriptive metadata, guiding developers toward what is possible rather than requiring them to know the right question
- The 10-step tutorial walks developers through progressive complexity, building the mental model needed to form good questions
- outputParameters with field renaming and nested object handling present API responses in domain-friendly terms, reducing the expertise needed to understand results
- Multi-step orchestration with cross-step data mapping shows developers how capabilities compose, teaching integration patterns by example
Naftiko Tomorrow
- Starter templates (Second Alpha) would provide opinionated examples for common integration scenarios, showing junior developers what questions are relevant for each pattern
- VS Code Agent Plugin with Naftiko Skills preset (Second Alpha) would offer guided, in-IDE workflows that prompt developers with the right questions at the right time
- HTML/Markdown format support (Second Alpha) would allow capabilities to serve rich explanatory content alongside structured data
- TechDocs integration (First Beta) would embed contextual documentation within the developer portal, surfacing relevant guidance before developers need to ask