How scrumatscale/official-guide works
Project type and purpose
• Type: An open-source documentation project (the official Scrum@Scale Guide).
• Purpose: Store, manage, translate, build, and publish a LaTeX-based guide (PDF/Word) and related assets for a global audience.
File structure
• Top-level files:
– README.md, guide-us-english.tex/pdf – the primary English LaTeX source and output.
– _config.yml – configuration (likely for Jekyll/GitHub Pages).
– .gitattributes, .gitignore – VCS settings.
• Directories:
– images/ – shared media assets used by the English guide.
– translations/ – subfolders for each locale; each contains .tex/.pdf/.docx and occasionally its own images folder.
• No explicit build scripts in repo, but conventions imply use of:
– LaTeX toolchain (pdflatex/xelatex)
– Optional CI (GitHub Actions) for automated builds
– Jekyll or static-site generator using _config.yml for publishing HTML site.
README for additional insights
• Format: LaTeX.
• Contribution process: GitHub Issues & Pull Requests.
• Biannual release cadence.
• Translations: community-driven, must conform to structure (guide-language.tex etc.).
Main components & interactions
a. Components:
1. Version Control System (GitHub Repo)
2. Source Content:
– Master LaTeX (guide-us-english.tex) + images
– Translations (per-locale .tex/.docx + localized assets)
3. Continuous Integration / Build Environment:
– LaTeX compiler
– Conversion tools (.docx transformers, if any)
4. Static-Site Generator (Jekyll via _config.yml)
5. Outputs:
– PDF & DOCX guide files
– Published HTML site (via GitHub Pages)
6. Consumers:
– End users (download PDFs, view translations, read online)
– Contributors (open Issues/PRs)
b. Relationships & Data Flow:
– Contributors push commits/PRs → GitHub Repo
– CI detects changes → triggers build pipeline
– Build pipeline invokes LaTeX compiler on guide-us-english.tex and per-locale .tex files
– Generated PDFs (and DOCX covers) are stored in output directories or artifacts
– Jekyll processes Markdown/HTML templates (README, translation landing pages)
– Final site is deployed to GitHub Pages
– End users access site or download assets
– Feedback via Issues/PRs loops back to Contributors
c. Architectural patterns / principles
– Content-oriented, folder-per-locale modularity
– CI/CD: automated build & deploy
– Separation of concerns: source vs. build vs. deployment vs. consumption
– Community-driven extensibility (easy addition of new language folders)
d. Key technologies & frameworks
– Git/GitHub (repo, Issues, PRs, Pages)
– LaTeX toolchain (pdflatex/xelatex)
– Static-site generator (Jekyll, configured by _config.yml)
– PDF and DOCX document formats
– Creative Commons license
• Clear labels for each component (e.g., “GitHub Repo,” “LaTeX Compiler,” “GitHub Pages”)
– Push → Build → Deploy → Access
– Feedback loop from Users → Issues → PRs