Documentation philosophy
Documentation is the backbone of effective engineering collaboration. It serves as a shared knowledge base, enabling teams to build, maintain, and scale complex systems with confidence. This document outlines our philosophy for creating high-quality, actionable, and accessible documentation, ensuring that every engineer can contribute to and benefit from a well-documented codebase. By adhering to these principles, we aim to foster a culture of clarity, ownership, and continuous improvement.
Principles
These principles govern the quality, structure, and usability of the content itself. They ensure that every engineer consuming our documentation can have a seamless and productive experience.
1. Clarity 💆🏻
Focus: We aim to provide clear and concise instructions, explanations, and code snippets. We strip away ambiguity to ensure the reader can immediately grasp the concept.
Why: We are dealing with highly complex domains, such as advanced Three.js shaders, React-Three-Fiber state management, and intricate clinical data parsing logic. Clarity ensures that this complexity is not magnified by confusing prose, making the "bar for scan-viewer contributions" as low as possible.
2. Comprehensiveness 🧠
Focus: Our guides cover a wide technical range, spanning from foundational setup to the deep specifics of our architecture.
Why: Documentation must address the full lifecycle of development. This includes how to set up a basic Typescript/Vite project, how the Viewer Core Library abstracts 3D primitives, and the comprehensive details of high-risk components like the CBCT processing logic or our Implant Copilot workflow.
3. Practicality 🔧
Focus: We include immediate, applicable examples, use cases, and best practices to help you apply knowledge in real-world scenarios.
Why: As an engineering tribe, our documentation must be actionable. We prioritize providing concrete code examples for tasks such as configuring a new 3D scene, defining a custom material with shaders, or securely integrating an AXS/cDX file specification—allowing for quick, copy-paste-and-adapt solutions.
4. Accessibility 🛗
Focus: The content is structured with consistent formatting, logical hierarchy, and appropriate technical depth to be approachable for users of all skill levels, from junior engineers to seasoned tech leads.
Why: Documentation is a primary tool for onboarding. By ensuring content is well-indexed, searchable, and progressively detailed (e.g., summary first, deep dive second), we create a clear, structured path for new team members to quickly become confident in contributing to our core systems.
Mission
1. Enable Distributed Ownership (Lowering the Bus Factor) 🚌
Focus: Proactively document all major features, complex refactorings, and high-risk domain areas before implementation is complete.
Why: This strategy ensures no single engineer is the sole knowledge owner of critical systems, such as the 3D manipulation core or specific dental coordinate transformations. By reducing the bus factor, we increase team resilience and dramatically lower the bar for external product teams to contribute to the shared Viewer Core Library.
2. Standardize Practices and Architectural Decisions 📐
Focus: Rigorously capture the rationale ("The Why") behind technical and strategic decisions, and define clear engineering standards.
Why: We use Architectural Decision Records (ADRs) and RFCs to document trade-offs and prevent future re-investigation into topics like state management or API design. We also centralize and enforce standards for Typescript usage, testing methodologies, and CI/CD pipelines to ensure code consistency across all clinical applications.
3. Treat External Contracts as Core Product Specs 🤝
Focus: Explicitly document the data and integration contracts that define our dependencies on internal and external partners.
Why: Our clinical workflow stability depends on reliably reading partner data. Documents like the AXS 3D Viewer File Export Specification and the structure of our internal container.json metadata (including elements like 4x4 Matrix Tuple and <transform> properties) are treated as critical, living product specifications. This ensures reliable parsing and visualization of clinical artifacts like implants and crowns.