This is an initiative to ensure all documentation complies completely with the **Documentation Style Guide section "[Documentation is the single source of truth (SSOT)](https://docs.gitlab.com/ee/development/documentation/styleguide.html#documentation-is-the-single-source-of-truth-ssot)"**. If you are participating in this epic, please read the latest content at that URL. We will use this spreadsheet to plan and track work https://docs.google.com/spreadsheets/d/1UtszDRdd7BynbaM5UejmRUuV8UFO09zWpqXQWFJQO8s/ (See Summary & EE tabs) **Phase 1:** 20% of GitLab CE/EE Documentation: May 6 - June 11. * Pages in Gitlab EE/CE: 708 * 20% of these pages: 142 * Pages assigned: 151 * Pages reviewed/merged: 151 ✅ 106.64% of goal has been achieved * Sunset glossary after migrating any useful content ✅ * Review GitLab's top 50 videos and include any that are useful (e.g. up to date and specific to feature or use case) and not already in docs: 8 ✅ * Add one YouTube video per section, where additional applicable videos exist: 5 ✅ ## Requirements For each page and section, we will do the following, correlating to the principles listed in our Style Guide 'SSOT' section linked above: - **Single Source of Truth** - Check the section for duplicate info and consolidate it, choosing a single source of truth page or section for that info and linking from other locations to that info. If the doc links out to another path outside this ‘section’ (outside the folder of docs for this audit) that may have overlapping info with this one, check that as well. If consolidating such content _across_ sections would require more extensive edits to the _other_ section that’s not part of this audit, ping @mikelewis with a recommendation on whether we should (a) create an issue instead, to prevent scope creep, OR (b) include those other pages in phase 1 (and potentially remove others, in exchange). - **All information** - Add a commented-out Troubleshooting subsection to the bottom of any doc that does not have it (except pages that are solely index pages), [per our template](https://docs.gitlab.com/ee/development/documentation/structure.html#template-for-new-docs). We will then produce a list of docs that have a complete (any content) section vs. empty Troubleshooting section to inspire Support and others to supplement these as cases arise. - **All media types** - Search [GitLab's YouTube videos](https://www.youtube.com/gitlab) for content on the topic of the section -- not each page, but the section. Include a link to a video that is relevant, mostly up to date with the latest version of GitLab, and would be helpful to someone who is reading the docs on this topic. - **No special types** - GitLab is currently not adding ‘special content types’ like tutorials, while we instead focus on improving existing content for completeness, accuracy, style, and structure. For this audit, while we won’t outright delete content that is a special type (e.g. tutorial), if a doc doesn’t fit our usual template, we should identify this, so we can properly consider how we can take it into account for further section improvement and doc standards. We'll do both of these: - (a) In the front matter of the doc, add _one or more_ `type` out of the following: `index`, `concepts`, `reference`, `howto`, `tutorial`, and/or an additional type (if you encounter one we haven't thought of - but ping it to #docs-team so we can be aware/discuss). For example: ```yaml --- type: reference, howto --- ``` Descriptions of each here: - `index`: Index / overview page. - `concepts`: What you need to know before using product. Informational, not instructional. E.g. Abstract ideas; explain meaning or benefit; can remain when product details change; support understanding of tasks; are read for background information. E.g. “Why X is important”. - `reference`: Covers what things are/do; core functionality instructions). Specific settings; facts without too much explanation; change with product changes; support correct execution of tasks; are read for detailed information. “Stages of X”. - `howto`: Specific use case instructions. - `tutorial`: Learn a process/concept by doing. - Note that we *will* remove/redistribute content that is *organized* by type, such as glossaries. See "Organize by topic, not by type." - (b) Because content types beyond the main feature reference/instructional material are harder to keep current, and may not be up to date -- **for pages that are purely tutorials/how-tos** -- add a note at the start of any page last updated more than 18 months ago that "Note: This process has not been updated since \[date\] and could be out of date. For the latest documentation on \[Feature X\], see \[Y\]."" Also, if you notice the content is out of date (e.g. old screenshots), change the words "could be" to "is". (To determine page age, do a `git log --follow -p <path/filename>`.) - **Link instead of summarize** - If, when linking to another page, we summarize the content of that other page -- more than a few words to simply convey what the other page is/contains or why to visit it -- remove the summary and streamline the context of the link to offer just the page title, with possibly a few words of introduction. E.g. this is good: “For more detail, see [GitLab CI/CD environment variables](#).” - **Organize by topic, not by type** - If you find a collection of items by type (e.g. a list of articles, videos, terms (glossary)), migrate the content to its relevant topic or feature-based section where it will be more easily found. Link to the new location(s) of content, when it's moved, so that it's easily found from locations where it is also relevant. - **Docs-first methodology** - This methodology is primarily geared for customer interactions, typically Support, starting with a case, rather than starting with a doc. But to help enable this, the same content-focused improvement as we're doing for 'all information' applies: adding the Troubleshooting section and reporting on these, as described in that section above. - **Meaningful introductions** - A key goal of the SSOT is to ensure there is a clear and obvious place to find all information, but that's not the case if you can't quickly identify the context and content of a page. This item is to ensure each page has an introduction to the topic and to the content that is found on the page, linking back to prerequisite knowledge (terms) or tasks as appropriate. This helps orient new readers who land on the page from search and makes the documentation more approachable. Additionally, we will review the 50 most popular YouTube videos and include links to all that are relevant to documentation readers. ## Process * In the [tracking sheet](https://docs.google.com/spreadsheets/d/1UtszDRdd7BynbaM5UejmRUuV8UFO09zWpqXQWFJQO8s/), mark each doc's columns with: * `yes` - if it already met the standard, per your review * `fixed` - if you fixed it to meet the standard * In the MR, briefly explain each fix you made, along with the standard above that it applies to. * In the sheet, under `type(s)`, identify when you've added type(s) to the frontmatter. ## Notes This initiative will assist with some existing issues: - Deprecate the glossary https://gitlab.com/gitlab-org/gitlab-ce/issues/58413 - Review/overhaul CI/CD docs https://gitlab.com/groups/gitlab-org/-/epics/784 - Review/improvements to GitLab Basics https://gitlab.com/groups/gitlab-org/-/epics/1179 Based on our findings, there is flexibility to change the set of pages we will cover (if we find higher priority work in another section/page), with the approval of @mikelewis and so long as this phase addresses the minimum number of docs (142+ / 20%+).