Release Management documentation guidelines

⚡ Warning: This page is a stub. Content on this page is therefore not complete.

The purpose of the guidelines below is to document the documentation writing process itself.

The end goal is to share knowledge and make sure that we have some minimal consistency in our documentation over time.

Release_Management Namespace

Our team namespace is Release_Management, don't create a RM page outside of this namespace.

If an existing page in a different namespace is migrated under our responsability, the page should be renamed to use our namespace. Renaming preserves history of edits.

Internal links to our namespace have this syntax (note the pipe before the title and the double brackets): [[Release_Management/Nightly|Firefox Nightly channel]]

Categories

We currently use two categories, one with our Namespace only which is used to inventory all of our pages and one for pages that describre a process.

If you create a page in our namespace, you should add the relecant categories to have them listed on our category pages

Example with a page named Chemspill_management:

[[category:Release_Management|Chemspill]] [[category:Release_Management:Processes|Chemspill]]

Note that above we put Chemspill after the pipe, this is a sorting key so as to have pages in alphabetical order.

If you redirect a page to another, remove the categories it belongs to in the source text to avoid having it listed twice with different names.

Header templates

We use 3 headers on pages that indicate if a page is:

1. Obsolete and dead {{RELEASE_MANAGEMENT_OBSOLETE}}
2. Needs an update {{RELEASE_MANAGEMENT_UPDATE_NEEDED}}
3. A stub for future content {{RELEASE_MANAGEMENT_STUB}}

Just add the above template call at the top of your page to get the banner inserted.

Here are the 3 banners:

⚡ Warning: The content of this page is obsolete and kept for archiving purposes of past processes.

⚡ Warning: This page hasn't been updated recently and may not be fully accurate or complete. In case of doubt, contact our release managers.

⚡ Warning: This page is a stub. Content on this page is therefore not complete.

Page titles

Please put a real title at the top of the page, otherwise the title is extracted from the URL which is not always ideal.

So as to do it, use this template call at the top of the page: {{DISPLAYTITLE:Release Management documentation guidelines}}

Process pages

All pages that describe a process (writing release notes, dealing with a chemspill, respinning nightlies…) should be added to the Processes category.

A process page should have a Process card on the right which gives an overview of the purpose, expected results and people involved in the process describred in the page.

Example:

The box above was automatically generated with the following template:

{{Processbox
  | Process name = Nightly respin
  | Purpose      = Update our users' broken nightlies
  | Why          = A patch on mozilla-central broke Nightly badly (crash, broken UI…)
  | Goals        = Nightly population retention
  | People       = Relman, releng
}}

The first section of the page should be called Summarized Process and be an ordered list of tasks to do.

The purpose is to give a list of steps to do for people that already did the process while still documenting the details and background information in the later sections for people that are learning the process or look for a specific information about the process.This way we maintain one document only for both new and experienced release managers.