How pmatulis/open-documentation-academy works
Main Components
• Documentation Task Tracker – Central module where documentation tasks (as GitHub issues) are filed, categorized, and managed. This is the core “engine” of the repository.
• Participating Project Directories – Separate directories for projects like ADsys, Landscape, Multipass, Snapcraft, Website, and WSL. Each of these houses reference material, how-to guides, tutorials, and explanations specific to that platform or tool.
• Automated Workflows – The .github/workflows folder (containing files like automatic-doc-checks.yml) represents CI/CD pipelines that help verify documentation quality, formatting, or compliance.
• Website/Documentation Build System – The “website” directory includes Sphinx configurations, Makefile, assets (e.g., fonts, static files) and documentation pages which combine to build the published documentation site.
• External Communication and Contribution Channels – While not directly part of the codebase, the README mentions external systems like GitHub issues, Discourse, Matrix, social channels, and calendars. These act as integrations or “interfaces” for community collaboration and mentoring.
Relationships and Data Flow
• The central task tracker (GitHub issues) interacts with various participating projects; each task is tagged with identifiers (for example, naming conventions such as “ADSys” or “Multipass”) that connect to more detailed documentation stored in the respective directories.
• Automated workflows (CI/CD pipelines) trigger based on commits or task changes, ensuring that documentation adheres to quality standards.
• The website build system aggregates the structured documentation (from directories like website/docs, website/library, etc.) to produce a coherent online presence.
• External integration points (community platforms, CLA verification) are represented as interfaces or external dependencies that interact with the repository’s contributions.
Architectural Patterns and Principles
• Modular Structure: Each major project (or participating project) has a dedicated directory with its own set of reference documents, how-to guides, and tutorials. This corresponds to a modular or micro-architecture approach.
• Separation of Concerns: The separation between documentation tasks (tracking, labels, guidelines) and the actual content of the documentation (participating project directories, website build system) is key. CI/CD (GitHub workflows) is distinct from content.
• Extensibility: With clear areas for how-to guides, explanations, references, and tutorial labels, the system supports extensible contributions and evolving documentation styles following standards like Diátaxis.
• Use of Automation: The inclusion of automated doc-check workflows reflects emphasis on quality assurance in documentation.
Technologies, Frameworks, or Libraries
• GitHub for source management and issue tracking.
• Sphinx for documentation generation (visible in the “website” directory with .sphinx configuration files, static assets, and Makefile).
• YAML configuration files for CI/CD automation.
• Markdown for writing documentation, seen throughout the repository.
• External integrations (e.g., Discourse, Matrix) as referenced in the README.