Adding New Chapters & Books
Relevant source files
The following files were used as context for generating this wiki page:
The "Architecture of Open Source Applications" (AOSA) project is an extensible collection of documentation describing the structure and design decisions of various open source projects. It is organized into distinct volumes, such as Volume 1, Volume 2, Performance (POSA), and 500 Lines or Less. The project relies on volunteer contributions to expand its library of architectural essays.
Adding new content involves adhering to specific directory structures, file naming conventions, and metadata requirements. Contributors are encouraged to describe reasonably large, well-known open source applications to help other developers learn from existing successes and mistakes.
Sources: CLAUDE.md, metadata/index.html.md:162-171, metadata/faq.html.md:126-135
Repository Structure and Organization
The repository is structured by volumes, each residing in its own primary directory. When adding a new book or volume, a new directory must be established at the root level. When adding a chapter, it must be placed within the appropriate volume directory.
Current Volume Directories
| Directory | Content Description |
|---|---|
volume1/ | 25 chapters on general applications (e.g., LLVM, Asterisk). |
volume2/ | 24 chapters on general applications (e.g., Git, nginx). |
posa/ | 12 chapters focused on performance. |
500lines/ | 22 chapters implementing systems in < 500 lines. |
metadata/ | Site-wide metadata, index, FAQ, and licensing information. |
Sources: CLAUDE.md:12-23
File Naming Conventions
New chapters must follow a strict naming pattern to ensure they are correctly ordered and identified:
{chapter-number}_{chapter-name}.html.md
- chapter-number: A two-digit number (e.g.,
01,02).00is reserved for introductions, and99is reserved for bibliographies. - chapter-name: The title of the application or topic in kebab-case.
Sources: CLAUDE.md:31-40
Content Guidelines for New Chapters
A new chapter should function as a "one-hour introduction" for a new developer joining the project. It should focus on high-level modules, communication, coordination, and the "why" behind design decisions rather than low-level implementation details like specific struct declarations.
Required Components
Each new chapter file should include:
- Markdown Content: Converted from HTML or written directly in Markdown.
- Architectural Diagrams: Visual representations of the system.
- Code Examples: Relevant snippets illustrating implementation.
- Author Attribution: Information about the contributors.
- References: Citations and links to external resources.
Sources: CLAUDE.md:46-51, metadata/faq.html.md:143-155
Content Submission Workflow
The following diagram illustrates the logical flow of contributing a new chapter:
The diagram shows the process from project selection to final index update.
Sources: CLAUDE.md:46-51, metadata/faq.html.md:126-140, metadata/index.html.md:162-171
Metadata and Indexing
Whenever a new chapter or volume is added, the central metadata files must be updated to reflect the new content. This ensures the web interface and navigation remain accurate.
Updating the Index
The file metadata/index.html.md serves as the primary Table of Contents. It contains tables for each volume listing the chapter number, title (linked to the file), and the author's name (linked to their bio).
Contributor Biographies
Authors must be added to the Introduction file of the respective volume (e.g., volume2/00_introduction.html.md). This includes a brief biography and professional background.
This sequence shows the necessary file updates across the repository when adding a new chapter.
Sources: metadata/index.html.md:38-42, volume2/00_introduction.html.md:45-50, CLAUDE.md:41-45
Licensing and Participation
All contributions must be made available under the Creative Commons Attribution 3.0 Unported license. This is a non-negotiable requirement to avoid legal complications and ensure the educational content remains accessible.
- Royalties: All royalties from sales of the books are donated to Amnesty International.
- Volunteer Coordination: Prospective authors should contact the coordinators at
gvwilson@third-bit.com.
Sources: metadata/faq.html.md:132-135, metadata/index.html.md:154-158, volume1/00_introduction.html.md:383-385
Summary
Adding new chapters and books to the AOSA project is a structured process designed to expand the collective knowledge of software architecture. By adhering to the established volume-based directory structure, file naming conventions, and metadata update procedures, contributors can provide professional-grade insights into complex open source systems while supporting charitable causes.