Technical Documentation

Proposal

Problem Statement

The team is spending excessive time trying to understand code functionality and business logic with insufficient documentation. Current practice leads to repeated discovery efforts, reliance on specific team members for institutional knowledge, and inefficiency.

Goals

1. Reduce time spent deciphering existing code functionality and business logic
2. Create maintainable documentation that doesn’t become outdated
3. Establish clear expectations for when and how to document code
4. Develop a consistent approach to documentation that works with the team’s workflow

Actions

1. Create a dedicated “#documentation” Slack channel to identify and discuss documentation gaps in real-time
2. During code review, examine quality of documentation, focusing on:
   • Documenting “why” decisions were made, not just “what” the code does
   • Prioritizing documentation of unusual or non-intuitive code decisions
   • Including comments at critical decision points in the code
   • Writing tests that clearly demonstrate expected behavior
3. Investigate Claude API integration with repositories for knowledge retrieval
4. Document business logic decisions in a central location with links from code

Discovery

The team’s discussion about documentation revealed several key perspectives on what constitutes valuable documentation and why it’s needed:

Documentation of “why” vs. “what”

• Bomee emphasized the importance of understanding why certain design decisions were made, not just what the code does
• Jeremy noted his challenge was “not knowing the business motivation” behind implementation choices
• The team distinguished between code documentation (what it does) and business logic documentation (why it exists)

Documentation locations and permanence

• François advocated for tests as documentation since they demonstrate expected behavior
• Jeremy argued for keeping documentation close to what it governs to prevent drift
• Several members debated whether comments in code are effective or become outdated too quickly
• The team considered centralized documentation vs. inline documentation

Core documentation needs

• Documentation of unusual or non-intuitive implementations (like null user IDs)
• Explanation of business processes that span multiple files
• Capturing institutional knowledge currently held by specific team members
• Providing context for future developers to understand design decisions

Practical concerns

• The risk of outdated documentation becoming misleading
• The time investment required to create and maintain documentation
• How to ensure documentation remains visible and useful
• Finding a balance between thorough documentation and developer efficiency

The team recognized that their greatest pain points weren’t about missing technical documentation of what code does, but rather the absence of context about why certain approaches were taken and how business processes flow through the system.

Debate

The team’s debate about potential solutions revealed several approaches to addressing their documentation challenges:

Documentation through testing

• François advocated that “the first step is to write a test for it” when code is difficult to understand
• This approach ensures documentation stays in sync with functionality
• Tests demonstrate what code should do in specific circumstances

Location of documentation

• Jeremy argued for keeping documentation close to the code it describes to prevent drift
• Bomee was less concerned about location: “I don’t care where the document. I just feel like there isn’t enough knowledge that is examinable”
• The team considered both centralized documentation and inline approaches

Documentation methods

• Maksym cautioned against code comments: “I’m against comments in the code because comments become obsolete really fast”
• Chuck suggested that critical documentation could exist in any of the relevant files
• Maksym proposed linking tickets to commits: “link ticket to every commit because then you can check in the blame history”
• The team discussed using AI tools to analyze their codebase and answer questions

Balance and maintainability

• Jeremy expressed concern about outdated documentation: “I’d rather have no documentation than wrong documentation”
• The team debated how much to document versus relying on clean, readable code
• Finding the right balance between thorough documentation and developer efficiency was a key consideration
• The team concluded that incremental improvement through feedback would be more effective than attempting a comprehensive documentation overhaul, with Jeremy’s proposed Slack channel serving as the starting point for addressing the most critical documentation gaps.

Stakeholders & “Safe To Try” Decision

Please add additional comments and/or vote.

Consent

• Jeremy
• Bomee
• Chuck
• Maksym
• François: Approved as safe-to-try, and maybe too safe to try? Do we need more teeth to it, e.g. with specific metrics to reach/owners milestones? E.g. all coders to identify what is in their mind the #1 most confusing code area, clean it up per actions above?

Advice

• Jason
• Naina
• Robin
• Jeff