We have some documentation for our deployment pipeline, GitLab, and the tools used in the pipeline—Blubber and Kokkuri.

But this documentation has some issues:

1. It's incomplete—some docs use the Divio documentation system while some are a few examples
2. It's spread out: Deployment Pipeline and Blubber on Wikitech, GitLab on MediaWiki, and Kokkuri lives in markdown on GitLab
3. Parts are out-dated, like the Deployment Pipeline page

My hope is we can improve this:

1. Finish out some of the docs with "TODOs" in them, for example: Enabling GitLab CI for a Project
2. Add docs focused on developers achieving specific tasks vs the tools, e.g., migrating your existing simple repository (covering GitLab, Gerrit, and Kokkuri), publishing a docker image from your service (which would cover GitLab, Kokkuri, and Blubber), etc
3. Agree on an information architecture/plan/place to put information (for example, Hosting a project on GitLab covers publishing docs, but localization updates lives under a different top-level url OR what should live under "Deployment Pipeline"...maybe nothing at this point :))

Summary of outcomes

Based on rounds of interviews with users and subject matter experts, we've made the following changes:

• Introduced a new deployment pipeline overview on mediawiki.org: Deploying services to production. This overview fully describes the process of deploying services using the new pipeline, with links to relevant resources and explanations of more complicated concepts.
• Restructured GitLab documentation on mediawiki.org by reorganizing the landing page and the GitLab Navigation template.
• Reviewed, updated, and improved documentation pages related to GitLab, Blubber, and Kokkuri.
• Marked outdated and deprecated content as such.
• Introduced GitLab-related categories on mediawiki.org.
• Added a mechanism to automatically generate Blubber documentation based on the JSON schema and publish it on doc.wikimedia.org.
• Created a repository with GitLab CI configuration examples for applications in five programming languages.

Stakeholders

• Technical Documentation
• Release Engineering

Project plan

• Kickoff phase
  • Project discovery and initial research
  • Kickoff meeting with members of the Release Engineering team
• Research phase
  • User research
  • First round of SME interviews
  • High-level collection review
    • Create a repository for pipeline testing and experiments
  • Formulate a project plan
    • Identify candidates for first improvements
    • Define long-term goals
    • Plan reviewed and accepted
• Implementation phase
  • First:
    • T349799: Create a high-level deployment pipeline overview
    • T352259: Review critical-path deployment pipeline documentation
  • Later:
    • T352262: Review supporting deployment pipeline documentation
    • T352264: Improve deployment pipeline documentation structure
  • Last:
    • T352273: Create repository with configuration files for common CI use cases
    • T352274: Write tutorials for common CI tasks