diff options
Diffstat (limited to 'doc/development/documentation/index.md')
| -rw-r--r-- | doc/development/documentation/index.md | 226 |
1 files changed, 89 insertions, 137 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 4e5b4a85a97..8ffddb9b669 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -4,48 +4,49 @@ description: Learn how to contribute to GitLab Documentation. # GitLab Documentation guidelines -- **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. -- **[Technical Articles](#technical-articles)**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/). -- **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs). +GitLab's documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions covering every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features, as well as the use of GitLab with other applications. -## Contributing to docs +In addition to this page, the following resources to help craft and contribute documentation are available: + +- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, and more. +- [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. +- [Workflow](workflow.md) - A landing page for our key workflows: + - [Feature-change documentation workflow](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. + - [Documentation improvement worflow](improvement-workflow.md) - New content not associated with a new feature. +- [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. +- [Site architecture](/doc/development/documentation/site_architecture/index.md) - How docs.gitlab.com is built. + +## Source and rendered locations -Whenever a feature is changed, updated, introduced, or deprecated, the merge -request introducing these changes must be accompanied by the documentation -(either updating existing ones or creating new ones). This is also valid when -changes are introduced to the UI. +Documentation for GitLab Community Edition (CE) and Enterprise Edition (EE), along with GitLab Runner and Omnibus, is published to [docs.gitlab.com](https://docs.gitlab.com). The documentation for CE and EE is also published within the application at `/help` on the domain of the GitLab instance. -The one responsible for writing the first piece of documentation is the developer who -wrote the code. It's the job of the Product Manager to ensure all features are -shipped with its docs, whether is a small or big change. At the pace GitLab evolves, -this is the only way to keep the docs up-to-date. If you have any questions about it, -ask a Technical Writer. Otherwise, when your content is ready, assign one of -them to review it for you. +At `/help`, only content for your current edition and version is included, whereas multiple versions' content is available at docs.gitlab.com. -We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything -is documented. +The source of the documentation is maintained in the following repository locations: -Whenever you submit a merge request for the documentation, use the -"Documentation" MR description template. If you're changing documentation -location, use the MR description template called "Change documentation -location" instead. +| Project | Path | +| --- | --- | +| [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) | +| [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ce/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | +| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | +| [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | -## Documentation workflow +Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. -Please read through the [documentation workflow](workflow.md) before getting started. +## Contributing to docs + +[Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community. -## Documentation structure +To ensure that GitLab docs keep up with changes to the product, special processes and responsibilities are in place concerning all [feature changes](feature-change-workflow.md)—i.e. development work that impacts the appearance, usage, or administration of a feature. -Follow through the [documentation structure guide](structure.md) for learning -how to structure GitLab docs. +Meanwhile, anyone can contribute [documentation improvements](improvement-workflow.md) large or small that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. ## Markdown and styles [GitLab docs](https://gitlab.com/gitlab-com/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) -as markdown engine. Check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) -for a complete Kramdown reference. +as its markdown rendering engine. See the [GitLab Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. -Follow the [documentation style guidelines](styleguide.md) strictly. +Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. ## Documentation directory structure @@ -58,7 +59,7 @@ all docs should be linked. Every new document should be cross-linked to its rela The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have been **deprecated** and the majority their docs have been moved to their correct location -in small iterations. Please don't create new docs in these folders. +in small iterations. Please do not create new docs in these folders. Organize docs by product area and subject, not type. ### Documentation files @@ -71,18 +72,23 @@ in small iterations. Please don't create new docs in these folders. ### Location and naming documents -The documentation hierarchy can be vastly improved by providing a better layout -and organization of directories. - -Having a structured document layout, we will be able to have meaningful URLs -like `docs.gitlab.com/user/project/merge_requests/index.html`. With this pattern, -you can immediately tell that you are navigating a user related documentation -and is about the project and its merge requests. - -Do not create summaries of similar types of content (e.g. an index of all articles, videos, etc.), -rather organize content by its subject (e.g. everything related to CI goes together) +Our goal is to have a clear hierarchical structure with meaningful URLs +like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, +you can immediately tell that you are navigating to user-related documentation +about project features; specifically about merge requests. Our site's paths match +those of our repository, so the clear structure also makes documentation easier to update. + +While the documentation is home to a variety of content types, we do not organize by content type. +For example, do not create groupings of similar media types (e.g. indexes of all articles, videos, etc.). +Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes +it difficult to browse for the information you need and difficult to maintain up-to-date content. +Instead, organize content by its subject (e.g. everything related to CI goes together) and cross-link between any related content. +Do not simply link out to GitLab technical blog posts. There should be an up-to-date +single source of truth on the topic within the documentation, and the top of the +blog post should be updated to link to that doc. + The table below shows what kind of documentation goes where. | Directory | What belongs here | @@ -90,14 +96,12 @@ The table below shows what kind of documentation goes where. | `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. | | `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. | | `doc/api/` | API related documentation. | -| `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. | +| `doc/development/` | Documentation related to the development of GitLab. Related process and style guides should go here. | | `doc/legal/` | Legal documents about contributing to GitLab. | | `doc/install/` | Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | | `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | ---- - **General rules & best practices:** 1. When creating a new document and it has more than one word in its name, @@ -126,18 +130,23 @@ The table below shows what kind of documentation goes where. `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. -If you are unsure where a document should live, you can ping `@axil` or `@marcia` in your -merge request. +If you are unsure where a document or a content addition should live, this should +not stop you from authoring and contributing. You can use your best judgment and +then ask the reviewer of your MR to confirm your decision, and/or ask a technical writer +at any stage in the process. The techncial writing team will review all documentation +changes, regardless, and can move content if there is a better place for it. ### Changing document location -Changing a document's location is not to be taken lightly. Remember that the -documentation is available to all installations under `help/` and not only to -GitLab.com or <http://docs.gitlab.com>. Make sure this is discussed with the -Documentation team beforehand. +Changing a document's location requires specific steps to be followed to ensure that +users can seamlessly access the new doc page, whether they are accesing content +on a GitLab instance domain at `/help` or at docs.gitlab.com. Be sure to ping a +GitLab technical writer if you have any questions during the process (such as +whether the move is necessary), and ensure that a technical writer reviews this +change prior to merging. -If you indeed need to change a document's location, do NOT remove the old -document, but rather replace all of its contents with a new line: +If you indeed need to change a document's location, do not remove the old +document, but rather replace all of its content with a new line: ```md This document was moved to [another location](path/to/new_doc.md). @@ -175,6 +184,7 @@ Things to note: - Since we also use inline documentation, except for the documentation itself, the document might also be referenced in the views of GitLab (`app/`) which will render when visiting `/help`, and sometimes in the testing suite (`spec/`). + You must search these paths for references to the doc and update them as well. - The above `git grep` command will search recursively in the directory you run it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` and will print the file and the line where this file is mentioned. @@ -202,7 +212,7 @@ This redirection method will not provide a redirect fallback on GitLab `/help`. it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that land on the doc via `/help`. -### Redirections for pages with Disqus comments +#### Redirections for pages with Disqus comments If the documentation page being relocated already has any Disqus comments, we need to preserve the Disqus thread. @@ -240,20 +250,26 @@ choices: | Ending in `-docs` | `123-update-api-issues-docs` | If your branch name matches any of the above, it will run only the docs -tests. If it doesn't, the whole test suite will run (including docs). +tests. If it does not, the whole application test suite will run (including docs tests). ## Merge requests for GitLab documentation Before getting started, make sure you read the introductory section "[contributing to docs](#contributing-to-docs)" above and the -[tech writing workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/) -for GitLab Team members. +[documentation workflow](workflow.md). - Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Documentation.md) - Use the correct [branch name](#branch-naming) - Label the MR `Documentation` - Assign the correct milestone (see note below) +Documentation will be merged if it is an improvement on existing content, +represents a good-faith effort to follow the template and style standards, +and is believed to be accurate. + +Further needs for what would make the doc even better should be immediately addressed +in a follow-up MR or issue. + NOTE: **Note:** If the release version you want to add the documentation to has already been frozen or released, use the label `Pick into X.Y` to get it merged into @@ -380,80 +396,14 @@ to merge changes that will break `master` from a merge request with a successful ## Docs site architecture -Read through [docs architecture](site_architecture/index.md) to learn -how we architecture, build, and deploy the docs site, <https://docs.gitlab.com>, and -to check all the assets and libraries available. +See the [Docs site architecture](site_architecture/index.md) page to learn +how we build and deploy the site at [docs.gitlab.com](https://docs.gitlab.com), and +to review all the assets and libraries in use. ### Global navigation -Read through the [global navigation](site_architecture/global_nav.md) doc. - -## General Documentation vs Technical Articles - -### General documentation - -General documentation is categorized by _User_, _Admin_, and _Contributor_, and describe what that feature is, what it does, and its available settings. - -### Technical Articles - -Technical articles replace technical content that once lived in the [GitLab Blog](https://about.gitlab.com/blog/), where they got out-of-date and weren't easily found. - -They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives. - -A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab. - -They should be placed in a new directory named `/article-title/index.md` under a topic-related folder, and their images should be placed in `/article-title/img/`. For example, a new article on GitLab Pages should be placed in `doc/user/project/pages/article-title/` and a new article on GitLab CI/CD should be placed in `doc/ci/examples/article-title/`. - -#### Types of Technical Articles - -- **User guides**: technical content to guide regular users from point A to point B -- **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B -- **Technical Overviews**: technical content describing features, solutions, and third-party integrations -- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach specific objectives - -#### Understanding guides, tutorials, and technical overviews - -Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`. - -A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them. - -- Live example: "[Static sites and GitLab Pages domains (Part 1)](../../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../../user/project/pages/getting_started_part_four.md)" - -A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B. -It does not only describes steps 2 and 3, but also shows you how to accomplish them. - -- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) - -A **technical overview** is a description of what a certain feature is, and what it does, but does not walk -through the process of how to use it systematically. - -- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/) - -#### Special format - -Every **Technical Article** contains a frontmatter at the beginning of the doc -with the following information: - -- **Type of article** (user guide, admin guide, technical overview, tutorial) -- **Knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced) -- **Author's name** and **GitLab.com handle** -- **Publication date** (ISO format YYYY-MM-DD) - -For example: - -```yaml ---- -author: John Doe -author_gitlab: johnDoe -level: beginner -article_type: user guide -date: 2017-02-01 ---- -``` - -#### Technical Articles - Writing Method - -Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team. +See the [Global navigation](site_architecture/global_nav.md) doc for information +on how the left-side navigation menu is built and updated. ## Previewing the changes live @@ -468,13 +418,13 @@ The live preview is currently enabled for the following projects: - <https://gitlab.com/gitlab-org/gitlab-runner> If your branch contains only documentation changes, you can use -[special branch names](#branch-naming) to avoid long running pipelines. +[special branch names](#branch-naming) to avoid long-running pipelines. For [docs-only changes](#branch-naming), the review app is run automatically. For all other branches, you can use the manual `review-docs-deploy-manual` job in your merge request. You will need at least Maintainer permissions to be able -to run it. In the mini pipeline graph, you should see an `>>` icon. Clicking on it will -reveal the `review-docs-deploy-manual` job. Hit the play button for the job to start. +to run it. In the mini pipeline graph, you should see a `>>` icon. Clicking it will +reveal the `review-docs-deploy-manual` job. Click the play button to start the job.  @@ -630,9 +580,10 @@ A file with `proselint` configuration must be placed in a #### `markdownlint` `markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases)) - are followed for Markdown syntax. Our [style guidelines](styleguide.md) elaborate on which choices - must be made when selecting Markdown syntax for GitLab documentation and this tool helps - catch deviations from those guidelines. + are followed for Markdown syntax. + Our [Documentation Style Guide](styleguide.md) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) + elaborate on which choices must be made when selecting Markdown syntax for + GitLab documentation. This tool helps catch deviations from those guidelines. `markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), either on a single Markdown file or on all Markdown files in a project. For example, to run @@ -655,7 +606,7 @@ markdownlint **/*.md The following sample `markdownlint` configuration modifies the available default rules to: -- Adhere to the [style guidelines](styleguide.md). +- Adhere to the [Documentation Style Guide](styleguide.md). - Apply conventions found in the GitLab documentation. - Allow the flexibility of using some inline HTML. @@ -694,9 +645,10 @@ For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configur placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For example, `~/.markdownlintrc`. -## Danger bot +## Danger Bot -GitLab uses [danger bot](https://github.com/danger/danger) for some elements in -code review. For docs changes in merge requests, whenever a change under `/doc` -is made, the bot leaves a comment for the author to mention `@gl-docsteam`, so -that the docs can be properly reviewed. +GitLab uses [Danger](https://github.com/danger/danger) for some elements in +code review. For docs changes in merge requests, whenever a change to files under `/doc` +is made, Danger Bot leaves a comment with further instructions about the documentation +process. This is configured in the Dangerfile in the GitLab CE and EE repo under +[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/danger/documentation). |