Why Does Our Team’s Documentation Fail? (1)

Documentation often fails not because people lack motivation, but because it depends on individual initiative and lacks clear standards. Interviews with a commerce domain and a server chapter showed that teams struggle to know what to document, how much detail to include, and whether their knowledge is accurate. Both organizations found that consolidating scattered knowledge into a shared system is the essential first step.

Documentation in Domains and Chapters

• Domains bring together developers, product owners, and designers around a business area such as commerce or advertising.
  • Their documentation focuses on product-related knowledge, including policies, terminology, and specifications.
• Chapters group people with the same profession, such as server or frontend engineers.
  • Their documentation focuses on shared technical knowledge, conventions, and tools.
• Dongjin works on consolidating internal knowledge across commerce and advertising domains, while Hyebin develops the company-wide documentation system “Todoc” and runs a documentation guild in the server chapter.

Different Starting Points

• The commerce domain already had strong awareness of documentation needs.
  • Members specifically requested terminology guides, policy documentation, experiment records, and API references.
  • Although writing standards were not clearly defined, people understood which documents would help their daily work.
• The server chapter was initially more hesitant.
  • Members had worked without documentation and had not experienced its benefits directly.
  • An AI chatbot gave poor answers because its source documents were incomplete or disorganized.
  • Improving the underlying documents gradually made the chatbot more useful, helping members recognize the value of shared knowledge.

Interviews Revealed the Real Obstacles

• Dongjin interviewed developers to identify knowledge gaps and determine what information should be recorded.
  • The interviews clarified the organization’s needs, even though solving those needs required additional work.
• Hyebin initially reviewed onboarding documents very thoroughly and repeatedly reminded people to complete them.
  • Interviews showed that contributors generally appreciated external review because it improved document quality.
  • The main problem was not a lack of motivation, but uncertainty:
    • What knowledge should be included?
    • How much detail is appropriate?
    • Is the information accurate enough to share?
• These findings shifted the focus from persuading people to write toward making documentation easier and safer to produce.

Problems Caused by Missing Documentation

• In a domain, scattered policies create collaboration bottlenecks.
  • A team modifying a feature may first have to search for the policy owned by another team.
  • Newcomers struggle to understand what they do not know, creating prolonged “unknown unknowns.”
• In a technical chapter, engineers often need to reconstruct the history behind unusual code.
  • They search old chat threads, try multiple keywords, or contact the original author.
  • More time may be spent assessing context and risk than implementing the change itself.
• Useful knowledge often remains private.
  • Engineers may assume everyone already knows it or worry that it is too trivial to share.
  • As a result, people repeatedly solve the same problems independently, reducing overall productivity.

Why Documentation Does Not Continue

• Documentation benefits the future, while current work usually feels more urgent.
• It is often treated as secondary work that requires a deliberate decision to begin.
• Authors may also feel responsible for maintaining documents indefinitely.
• Without documentation embedded in normal workflows, every update depends on personal willpower.
• AI tools can reduce the effort of drafting and maintaining documents, but unclear standards and fear of being wrong remain significant barriers.

Both organizations reached the same starting point: gather scattered knowledge in one accessible place, then integrate writing, review, and updates into everyday work rather than relying on individual motivation.