Why Does Our Team’s Documentation Fail? (2) (opens in new tab)

Documentation succeeds not through individual resolve, but through centralized knowledge, clear purpose, and systems that reduce the fear of being wrong. Interviews across a commerce domain and a server-development chapter show that documentation strategies must match an organization’s existing maturity, audience, and work patterns. AI lowers the cost of writing and sharing knowledge, while also requiring more deliberate document organization.

Lessons from Early Attempts

• The commerce wiki was initially designed as a self-service platform supported by workshops and guilds.
• Workshops could encourage a first contribution, but sustaining second, third, and later contributions was difficult.
• In the Ads domain, documentation was already strong, so the better approach was to respect existing conventions and help people locate knowledge rather than create another system.
• Organizations with little documentation need to build foundational knowledge; organizations with mature documentation need better discovery and maintenance.

Reducing the Fear of Asking and Writing

• Developers often avoid asking questions because doing so publicly reveals what they do not know.
• They may also hesitate to publish documentation because they fear their knowledge could be inaccurate.
• The team addresses this through:
  • “Lee’s Development Consultation Week,” which normalizes questions and encourages teammates to answer questions Lee cannot address.
  • A daily knowledge bot, “Ha,” which shares short server-development tips automatically.
• Correcting or adding to an existing shared post feels easier than writing a complete document from scratch.

How AI Has Changed Documentation

• AI makes it faster to create initial drafts and distribute knowledge through chatbots.
• It also enables measurement of knowledge flow, including:
  • The number of questions asked.
  • Whether teammates provide answers.
  • The quality and content of those answers.
  • The number of new documents and week-over-week growth.
• These metrics reveal knowledge gaps and recurring questions without manually reviewing every channel.
• AI also creates a need for more detailed internal context than human readers typically require.
• Commerce therefore separates:
  • Central, human-friendly documentation managed by technical writers.
  • Team-repository documentation containing detailed, team-specific context useful to AI but unnecessary for everyone else.

Shared Principles and Organizational Differences

• Both domains and chapters should centralize knowledge and avoid spreading it across too many channels.
• Domains typically:
  • Connect documentation to products and code.
  • Change rapidly.
  • Serve a broad and varied audience.
• Chapters typically:
  • Document conventions, working methods, and professional knowledge.
  • Change more slowly.
  • Focus on productivity and capability development.
  • Have a clearer audience, such as a specific role or discipline.
• Domain documentation should be understandable even to non-developers, since developers may also lack context outside their specialties.
• Separating guides, capability-based policies, glossaries, and metrics helps different readers find documents suited to their needs.

Where to Begin

• First diagnose the organization’s current documentation maturity by asking what people do when they get stuck:
  • Ask coworkers or search chat: foundational documentation is largely missing.
  • Search documents: assess whether information is easy to find; fill gaps if searches fail.
  • Ask an AI or bot: evaluate whether answers are accurate and whether the underlying documents are complete, current, centralized, and sufficiently contextualized.
• Define the specific problem driving documentation, rather than starting with a vague goal.
• Begin with a focused need, such as creating a glossary for inconsistent terminology or building references for sharing knowledge with other teams.

The practical recommendation is to centralize knowledge, identify the organization’s biggest documentation gap, and build a low-friction system where people can contribute, correct, and consume information without relying solely on personal effort.