Why Does Our Team’s Documentation Fail? (1) (opens in new tab)
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.