How pjmssb/eng-practices works
Main Components
• Documentation Repository: Treat the entire project as a content management system for engineering guidelines.
• Review Guidelines:
– Developer Section (“Change Author’s Guide”): Contains files and indexes under review/developer (e.g., index.md, cl-descriptions.md, handling-comments.md, etc.).
– Reviewer Section (“Code Reviewer’s Guide”): Contains files and indexes under review/reviewer (e.g., index.md, comments.md, looking-for.md, etc.).
• Configuration & Metadata: Files such as _config.yml (likely used by a static site generator) and README.md that provide site configuration and overall project description.
• Licensing: LICENSE file that governs usage and redistribution.
Relationships and Interactions
• The top-level “Google Engineering Practices Documentation” component branches into the Review Guidelines, which then split into two distinct categories—developer and reviewer guidelines.
• Each category has its own index file and supporting markdown files that are linked together. For example, review/index.md acts as an entry point, which then connects to both the developer and reviewer components. The subcomponents will typically reference each other via hyperlinks, creating a navigable documentation network.
• The configuration file (_config.yml) directly supports the deployment and styling/layout of the content, interfacing with the underlying static site generator (perhaps Jekyll or a similar tool).
Architectural Patterns and Design Principles
• Navigation and Indexing: Notice that each subfolder has an index.md file, suggesting a hierarchy of information.
• External Integration: Although it is a documentation project, recognize that the _config.yml and references to licensing indicate potential integration with external systems (e.g., open-source version control repositories or CI/CD pipelines for documentation builds).