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.
Read original(opens in new tab)