Skip to content

G
gitlab-ce
Commit eab7e3c8 authored by Sid Sijbrandij's avatar Sid Sijbrandij
Browse files
Options

Merge branch 'documentation-development-docs' into 'master' 

Documentation process/policy updates to foster contributions to docs as SSOT

See merge request gitlab-org/gitlab-ce!23951
parents 4d875a2b a4e7b770
Show whitespace changes
Inline Side-by-side
Showing with 367 additions and 425 deletions
doc/development/documentation/feature-change-workflow.md 0 → 100644
View file @ eab7e3c8
---
description: How to add docs for new or enhanced GitLab features.
---
# Documentation process at GitLab
At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.
- **Developers**: Author/update documentation in the same MR as their code, and
merge it by the feature freeze for the assigned milestone. Request technical writer
assistance if needed.
- **Product Managers** (PMs): In the issue for all new and enhanced features,
confirm the documentation requirements, plus the mentioned feature description
and use cases, which can be reused in docs. They can bring in a technical
writer for discussion or help, and can be called upon themselves as a doc reviewer.
- **Technical Writers**: Review doc requirements in issues, track issues and MRs
that contain docs changes, help with any questions throughout the authoring/editing process,
and review all new and updated docs content after it's merged (unless a pre-merge
review request is made).
Beyond this process, any member of the GitLab community can also author documentation
improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md).
## When documentation is required
Documentation must be delivered whenever:
- A new or enhanced feature is shipped that impacts the user/admin experience
- There are changes to the UI or API
- A process, workflow, or previously documented feature is changed
- A feature is deprecated or removed
Documentation is not required when a feature is changed on the backend
only and does not directly affect the way that any user or
administrator would interact with GitLab. For example, a UI restyling that offers
no difference in functionality may require documentation updates if screenshots
are now needed, or need to be updated.
NOTE: **Note:**
When revamping documentation, if unrelated to the feature change, this should be submitted
in its own MR (using the [documentation improvement workflow](improvement-workflow.md))
so that we can ensure the more time-sensitive doc updates are merged with code by the freeze.
## Documenting a new or changed feature
To follow a consistent workflow every month, documentation changes
involve the Product Managers, the developer who shipped the feature,
and the Technical Writing team. Each role is described below.
### 1. Product Manager's role
The Product Manager (PM) should confirm or add the following items in the issue:
- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md).
- The documentation requirements for the developer working on the docs.
- What new page, new subsection of an existing page, or other update to an existing page/subsection is needed.
- Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected.
- Suggested title of any page or subsection, if applicable.
- Label the issue with `Documentation` and `docs:P1` in addition to the `Deliverable` label and correct milestone.
Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone.
### 2. Developer's role
As a developer, you must ship the documentation with the code of the feature that
you are creating or updating. The documentation is an essential part of the product.
- New and edited docs should be included in the MR introducing the code, and planned
in the issue that proposed the feature. However, if the new or changed doc requires
extensive collaboration or conversation, a separate, linked issue can be used for the planning process.
- Use the [Documentation guidelines](index.md), as well as other resources linked from there,
including the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
- If you need any help to choose the correct place for a doc, discuss a documentation
idea or outline, or request any other help, ping the Technical Writer for the relevant
[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
in your issue or MR, or write within `#docs` on the GitLab Slack.
- The docs must be merged with the code **by the feature freeze date**, otherwise
- the feature cannot be included with the release.<!-- TODO: Policy/process for feature-flagged issues -->
Prior to merge, documentation changes commited by the developer must be reviewed by:
* the person reviewing the code and merging the MR.
* optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested.
After merging, documentation changing are reviewed by:
* a technical writer (for clarity, structure, grammar, etc).
* optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used).
Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset.
### 3. Technical Writer's role
**Planning**
- Once an issue contains a Documentation label and an upcoming milestone, a
technical writer reviews the listed documentation requirements, which should have
already been reviewed by the PM. (These are non-blocking reviews; developers should
not wait to work on docs.)
- Monitor the documentation needs of issues assigned to the current and next milestone,
and participate in any needed discussion on docs planning with the dev, PM, and others.
**Review**
- Techncial writers provide non-blocking reviews of all documentation changes,
typically after the change is merged. However, if the docs are ready in the MR while
we are awaiting other work in order to merge, the technical writer's review can commence early.
- The technical writer will confirm that the doc is clear, grammatically correct,
and discoverable, while avoiding redundancy, bad file locations, typos, broken links,
etc. The technical writer will review the documentation for the following, which
the developer and code reviewer should have already made a good-faith effort to ensure:
- Clarity.
- Relevance (make sure the content is appropriate given the impact of the feature).
- Location (make sure the doc is in the correct dir and has the correct name).
- Syntax, typos, and broken links.
- Improvements to the content.
- Accordance to the [Documentation Style Guide](styleguide.md) and [structure/template](structure.md).
doc/development/documentation/improvement-workflow.md 0 → 100644
View file @ eab7e3c8
---
description: How to improve GitLab's documentation.
---
# Documentation improvement workflow
Anyone can contribute a merge request or create an issue for GitLab's documentation.
This page covers the process for any contributions to GitLab's docs that are
not part of feature development. If you are looking for information on updating
GitLab's docs as is required with the development and release of a new feature
or feature enhancement, see the [feature-change documentation workflow](feature-change-workflow.md).
## Who updates the docs
Anyone can contribute! You can create a merge request with documentation
when you find errors or other room for improvement in an existing doc, or when you
have an idea for all-new documentation that would help a GitLab user or admin
to achieve or improve their DevOps workflows.
## How to update the docs
- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page,
including linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
- Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines).
- If you need any help to choose the correct place for a doc, discuss a documentation
idea or outline, or request any other help, ping the Technical Writer for the relevant
[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages)
in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace.
## Merging
Anyone with master access to the affected GitLab project can merge documentation changes.
This person must make a good-faith effort to ensure that the content is clear
(sufficiently easy for the intended audience to navigate and understand) and
that it meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md).
If the author or reviewer has any questions, or would like a techncial writer's review
before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
## Technical Writer review
The technical writing team reviews changes after they are merged, unless a prior
review is requested.
## Other ways to help
If you have ideas for further documentation resources that would be best
considered/handled by technical writers, devs, and other SMEs, please create an issue.
doc/development/documentation/index.md
View file @ eab7e3c8
......@@ -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.gitab.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.
![Manual trigger a docs build](img/manual_build_docs.png)
......@@ -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).
doc/development/documentation/site_architecture/index.md
View file @ eab7e3c8
......@@ -2,11 +2,18 @@
description: "Learn how GitLab's documentation website is architectured."
---
# Docs site architecture
# Documentation site architecture
Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs)
and deploy it to <https://docs.gitlab.com>.
## Repository
While the source of the documentation content is stored in GitLab's respective product
repositories, the source that is used to build the documentation site _from that content_
is located at https://gitlab.com/gitlab-com/gitlab-docs. See the README there for
detailed information.
## Assets
To provide an optimized site structure, design, and a search-engine friendly
......
doc/development/documentation/structure.md
View file @ eab7e3c8
---
description: Learn the how to correctly structure GitLab documentation.
description: What to include in GitLab documentation pages.
---
# Documentation structure
# Documentation structure and template
For consistency throughout the documentation, it's important to maintain the same
structure among the docs.
This document will help you determine how to structure a page within GitLab's
documentation and what content to include. These standards help ensure consistency
and completeness throughout the documentation, and they make it easier to contribute.
Before getting started, read through the following docs:
Before getting started, familiarize yourself with [GitLab's Documentation guidelines](index.md)
and the section on Content in the [Style Guide](styleguide.md).
- [Contributing to GitLab documentation](index.md#contributing-to-docs)
- [Merge requests for GitLab documentation](index.md#merge-requests-for-gitlab-documentation)
- [Branch naming for docs-only changes](index.md#branch-naming)
- [Documentation directory structure](index.md#documentation-directory-structure)
- [Documentation style guidelines](styleguide.md)
- [Documentation workflow](workflow.md)
## Components of a documentation page
## Documentation blurb
Most pages will be dedicated to a specifig GitLab feature or to a use case that involves
one or more features, potentially in conjunction with third-party tools.
Every document should include the following content in the following sequence:
Every feature or use case document should include the following content in the following sequence,
with exceptions and details noted below and in the template included on this page.
- **Feature name**: defines an intuitive name for the feature that clearly
states what it is and is consistent with any relevant UI text.
- **Feature overview** and description: describe what it is, what it does, and in what context it should be used.
- **Use cases**: describes real use case scenarios for that feature.
- **Requirements**: describes what software and/or configuration is required to be able to
use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial.
For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc.
Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement.
(Another doc page, a third party application's site, etc.)
- **Instructions**: clearly describes the steps to use the feature, leaving no gaps.
- **Troubleshooting** guide (recommended but not required): if you know beforehand what issues
one might have when setting it up, or when something is changed, or on upgrading, it's
important to describe those too. Think of things that may go wrong and include them in the
docs. This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask. Answering them beforehand only makes your
document better and more approachable.
- **Title**: Top-level heading with the feature name, or a use case name, which would start with
a verb, like Configuring, Enabling, etc.
- **Introduction**: A couple sentences about the subject matter and what's to be found on this page.
- **Overview** Describe what it is, what it does, and in what context it should be used.
- **Use cases**: describes real use case scenarios for that feature/configuration.
- **Requirements**: describes what software, configuration, account, or knowledge is required.
- **Instructions**: One or more sets of detailed instructions to follow.
- **Troubleshooting** guide (recommended but not required).
For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs).
For additional details on each, see the [template for new docs](#template-for-new-docs),
below.
### Feature overview and use cases
Note that you can include additional subsections, as appropriate, such as 'How it Works', 'Architecture',
and other logicial divisions such as pre- and post-deployment steps.
Every major feature (regardless if present in GitLab Community or Enterprise editions)
should present, at the beginning of the document, two main sections: **overview** and
**use cases**. Every GitLab EE-only feature should also contain these sections.
**Overview**: as the name suggests, the goal here is to provide an overview of the feature.
Describe what is it, what it does, why it is important/cool/nice-to-have,
what problem it solves, and what you can do with this feature that you couldn't
do before.
**Use cases**: provide at least two, ideally three, use cases for every major feature.
You should answer this question: what can you do with this feature/change? Use cases
are examples of how this feature or change can be used in real life.
Examples:
- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html)
- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html)
Note that if you don't have anything to add between the doc title (`<h1>`) and
the header `## Overview`, you can omit the header, but keep the content of the
overview there.
> **Overview** and **use cases** are required to **every** Enterprise Edition feature,
and for every **major** feature present in Community Edition.
### Discoverability
Your new document will be discoverable by the user only if:
- Crosslinked from the higher-level index (e.g., Issue Boards docs
should be linked from Issues; Prometheus docs should be linked from
Monitoring; CI/CD tutorials should be linked from CI/CD examples).
- When referencing other GitLab products and features, link to their
respective docs; when referencing third-party products or technologies,
link out to their external sites, documentation, and resources.
- The headings are clear. E.g., "App testing" is a bad heading, "Testing
an application with GitLab CI/CD" is much better. Think of something
someone will search for and use these keywords in the headings.
## Documentation template for new docs
## Template for new docs
To start a new document, respect the file tree and file name guidelines,
as well as the style guidelines. Use the following template:
```md
<!--Follow the Style Guide when working on this document. https://docs.gitlab.com/ee/development/documentation/styleguide.html
When done, remove all of this commented-out text, except a commented-out Troubleshooting section,
which, if empty, can be left in place to encourage future use.-->
---
description: "short document description." # Up to ~200 chars long. They will be displayed in Google Search Snippets.
description: "Short document description." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here.
---
# Feature Name **[TIER]** (1)
# Feature Name or Use Case Name **[TIER]** (1)
<!--If writing about a use case, drop the tier, and start with a verb, e.g. 'Configuring', 'Implementing', + the goal/scenario-->
> [Introduced](link_to_issue_or_mr) in GitLab Tier X.Y (2).
<!--For pages on newly introduced features, add the following line. If only some aspects of the feature have been introduced, specify what parts of the feature.-->
> [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2).
A short description for the feature (can be the same used in the frontmatter's
`description`).
An introduction -- without its own additional header -- goes here.
Offer a very short description of the feature or use case, and what to expect on this page.
(You can reuse this content, or part of it, for the front matter's `description` at the top of this file).
## Overview
To write the feature overview, you should consider answering the following questions:
The feature overview should answer the following questions:
- What is it?
- What is this feature or use case?
- Who is it for?
- What is the context in which it is used and are there any prerequisites/requirements?
- What can the user do with it? (Be sure to consider multiple audiences, like GitLab admin and developer-user.)
- What are the benefits to using it over any alternatives?
- What can the audience do with this? (Be sure to consider all applicable audiences, like GitLab admin and developer-user.)
- What are the benefits to using this over any alternatives?
## Use cases
Describe one to three use cases for that feature. Give real-life examples.
Describe some use cases, typically in bulleted form. Include real-life examples for each.
If the page itself is dedicated to a use case, this section can usually include more specific scenarios
for use (e.g. variations on the main use case), but if that's not applicable, the section can be omitted.
Examples of use cases on feature pages:
- CE and EE: [Issues](../../user/project/issues/index.md#use-cases)
- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md)
- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html)
- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html)
## Requirements
State any requirements, if any, for using the feature and/or following along with the tutorial.
State any requirements for using the feature and/or following along with the instructions.
The only assumption that is redundant and doesn't need to be mentioned is having an account
on GitLab.
These can include both:
- technical requirements (e.g. an account on a third party service, an amount of storage space, prior configuration of another feature)
- prerequisite knowledge (e.g. familiarity with certain GitLab features, cloud technologies)
Link each one to an appropriate place for more information.
## Instructions
("Instructions" is not necessarily the name of the heading)
"Instructions" is usually not the name of the heading.
This is the part of the document where you can include one or more sets of instructions, each to accomplish a specific task.
Headers should describe the task the reader will achieve by following the instructions within, typically starting with a verb.
Larger instruction sets may have subsections covering specific phases of the process.
- Write a step-by-step guide, with no gaps between the steps.
- Start with an h2 (`##`), break complex steps into small steps using
subheadings h3 > h4 > h5 > h6. _Never skip the hierarchy level, such
subheadings h3 > h4 > h5 > h6. _Never skip a hierarchy level, such
as h2 > h4_, as it will break the TOC and may affect the breadcrumbs.
- Use short and descriptive headings (up to ~50 chars). You can use one
single heading `## How it works` for the instructions when the feature
single heading like `## Configuring X` for instructions when the feature
is simple and the document is short.
- Be clear, concise, and stick to the goal of the doc: explain how to
use that feature.
- Use inclusive language and avoid jargons, as well as uncommon and
fancy words. The docs should be clear and easy to understand.
- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
- Always provide internal and external reference links.
- Always link the doc from its higher-level index.
<!-- ## Troubleshooting
Add a troubleshooting guide when possible/applicable. -->
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
---
......
doc/development/documentation/styleguide.md
View file @ eab7e3c8
---
description: 'Writing styles, markup, formatting, and reusing regular expressions throughout the GitLab Documentation.'
description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.'
---
# Documentation style guidelines
# Documentation Style Guide
The documentation style guide defines the markup structure used in
GitLab documentation. Check the
[documentation guidelines](index.md) for general development instructions.
Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
See the GitLab handbook for the [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
For help adhering to the guidelines, see [linting](index.md#linting).
For programmatic help adhering to the guidelines, see [linting](index.md#linting).
## Files
......@@ -40,13 +40,36 @@ Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}
## Content
- Make sure that the documentation is added in the correct
[directory](index.md#documentation-directory-structure), linked from its
higher-level index, and linked from other related pages.
These guidelines help toward the goal of having every user's search of documentation
yield a useful result, and ensuring content is helpful and easy to consume.
- What to include:
- Any and all helpful information, processes, and tips for implementing,
using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot)
for this information.
- 'Risky' or niche problem-solving steps. There is no reason to withhold these or
store them elsewhere; simply include them along with the rest of the docs including all necessary
detail, such as specific warnings and caveats about potential ramifications.
- Any content types/sources, if relevant to users or admins. You can freely
include presentations, videos, etc.; no matter who it was originally written for,
if it is helpful to any of our audiences, we can include it. If an outside source
that's under copyright, rephrase, or summarize and link out; do not copy and paste.
- All applicable subsections as described on the [structure and template](structure.md) page,
with files organized in the [correct directory](index.md#documentation-directory-structure).
- To ensure discoverability, link to each doc from its higher-level index page and other related pages.
- When referencing other GitLab products and features, link to their
respective docs; when referencing third-party products or technologies,
link out to their external sites, documentation, and resources.
- Do not duplicate information.
- Be brief and clear.
- Unless there's a logical reason not to, structure the document in alphabetical order
(headings, tables, and lists).
- Structure content in alphabetical order in tables, lists, etc., unless there is
a logical reason not to (for example, when mirroring the UI or an ordered sequence).
## Language
- Use inclusive language and avoid jargon, as well as uncommon
words. The docs should be clear and easy to understand.
- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
- Be clear, concise, and stick to the goal of the doc.
- Write in US English.
- Capitalize "G" and "L" in GitLab.
- Use title case when referring to [features](https://about.gitlab.com/features/) or
......
doc/development/documentation/workflow.md
View file @ eab7e3c8
---
description: Learn the process of shipping documentation for GitLab.
description: Learn the processes for contributing to GitLab's documentation.
---
# Documentation process at GitLab
# Documentation workflows at GitLab
At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.
Documentation workflows at GitLab differ depending on the reason for the change. The two types of documentation changes are:
- Product Managers (PMs): in the issue for all new and updated features,
PMs include specific documentation requirements that the developer who is
writing or updating the docs must meet, along with feature descriptions
and use cases. They call out any specific areas where collaborating with
a technical writer is recommended, and usually act as the first reviewer
of the docs.
- Developers: author documentation and merge it on time (up to a week after
the feature freeze).
- Technical Writers: review each issue to ensure PM's requirements are complete,
help developers with any questions throughout the process, and act as the final
reviewer of all new and updated docs content before it's merged.
## Requirements
Documentation must be delivered whenever:
- A new feature is shipped
- There are changes to the UI
- A process, workflow, or previously documented feature is changed
Documentation is not required when a feature is changed on the backend
only and does not directly affect the way that any regular user or
administrator would interact with GitLab.
NOTE: **Note:**
When refactoring documentation, it should be submitted in its own MR.
**Do not** join new features' MRs with refactoring existing docs, as they might have
different priorities.
NOTE: **Note:**
[Smaller MRs are better](https://gitlab.com/gitlab-com/blog-posts/issues/185#note_4401010)! Do not mix subjects, and ship the smallest MR possible.
### Documentation review process
The docs shipped by the developer should be reviewed by the PM (for accuracy) and a Technical Writer (for clarity and structure).
#### Documentation updates that require Technical Writer review
Every documentation change that meets the criteria below must be reviewed by a Technical Writer
to ensure clarity and discoverability, and avoid redundancy, bad file locations, typos, broken links, etc.
Within the GitLab issue or MR, ping the relevant technical writer for the subject area. If you're not sure who that is,
ping any of them or all of them (`@gl\-docsteam`).
A Technical Writer must review documentation updates that involve:
- Docs introducing new features
- Changing documentation location
- Refactoring existing documentation
- Creating new documentation files
If you need any help to choose the correct place for a doc, discuss a documentation
idea or outline, or request any other help, ping a Technical Writer on your issue, MR,
or on Slack in `#docs`.
#### Skip the PM's review
When there's a non-significant change to the docs, you can skip the review
of the PM. Add the same labels as you would for a regular doc change and
assign the correct milestone. In these cases, assign a Technical Writer
for approval/merge, or mention `@gl\-docsteam` in case you don't know
which Tech Writer to assign for.
#### Skip the entire review
When the MR only contains corrections to the content (typos, grammar,
broken links, etc), it can be merged without the PM's and Tech Writer's review.
## Documentation structure
Read through the [documentation structure](structure.md) docs for an overview.
## Documentation workflow
To follow a consistent workflow every month, documentation changes
involve the Product Managers, the developer who shipped the feature,
and the Technical Writing team. Each role is described below.
### 1. Product Manager's role in the documentation process
The Product Manager (PM) should add to the feature issue:
- Feature name, overview/description, and use cases, for the [documentation blurb](structure.md#documentation-blurb)
- The documentation requirements for the developer working on the docs
- What new page, new subsection of an existing page, or other update to an existing page/subsection is needed.
- Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected
- Suggested title of any page or subsection, if applicable
- Label the issue with `Documentation`, `Deliverable`, `docs:P1`, and assign
the correct milestone
### 2. Developer's role in the documentation process
As a developer, or as a community contributor, you should ship the documentation
with the feature, as in GitLab the documentation is part of the product.
The docs can either be shipped along with the MR introducing the code, or,
alternatively, created from a follow-up issue and MR.
The docs should be shipped **by the feature freeze date**. Justified
exceptions are accepted, as long as the [following process](#documentation-shipped-late)
and the missed-deliverable due date (the 14th of each month) are both respected.
#### Documentation shipped in the feature MR
The developer should add to the feature MR the documentation containing:
- The [documentation blurb](structure.md#documentation-blurb): copy the
feature name, overview/description, and use cases from the feature issue
- Instructions: write how to use the feature, step by step, with no gaps.
- [Crosslink for discoverability](structure.md#discoverability): link with
internal docs and external resources (if applicable)
- Index: link the new doc or the new heading from the higher-level index
for [discoverability](#discoverability)
- [Screenshots](styleguide.md#images): when necessary, add screenshots for:
- Illustrating a step of the process
- Indicating the location of a navigation menu
- Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign
the correct milestone
- Assign the PM for review
- When done, mention the `@gl\-docsteam` in the MR asking for review
- **Due date**: feature freeze date and time
#### Documentation shipped in a follow-up MR
If the docs aren't being shipped within the feature MR:
- Create a new issue mentioning "docs" or "documentation" in the title (use the Documentation issue description template)
- Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>`
(product label == CI/CD, Pages, Prometheus, etc)
- Add the correct milestone
- Create a new MR for shipping the docs changes and follow the same
process [described above](#documentation-shipped-in-the-feature-mr)
- Use the MR description template called "Documentation"
- Add the same labels and milestone as you did for the issue
- Assign the PM for review
- When done, mention the `@gl\-docsteam` in the MR asking for review
- **Due date**: feature freeze date and time
#### Documentation shipped late
Shipping late means that you are affecting the whole feature workflow
as well as other teams' priorities (PMs, tech writers, release managers,
release post reviewers), so every effort should be made to avoid this.
If you did not ship the docs within the feature freeze, proceed as
[described above](#documentation-shipped-in-a-follow-up-mr) and,
besides the regular labels, include the labels `Pick into X.Y` and
`missed-deliverable` in the issue and the MR, and assign them the correct
milestone.
The **due date** for **merging** `missed-deliverable` MRs is on the
**14th** of each month.
### 3. Technical Writer's role in the documentation process
- **Planning**
- Once an issue contains a Documentation label and the current milestone, a
technical writer reviews the Product Manager's documentation requirements.
- Once the documentation requirements are approved, the technical writer can
work with the developer to discuss any documentation questions and plans/outlines, as needed.
- **Review** - A technical writer must review the documentation for:
- Clarity
- Relevance (make sure the content is appropriate given the impact of the feature)
- Location (make sure the doc is in the correct dir and has the correct name)
- Syntax, typos, and broken links
- Improvements to the content
- Accordance to the [docs style guide](styleguide.md)
<!-- TBA: issue and MR description templates as part of the process -->
<!--
## New features vs feature updates
- TBA:
- Describe the difference between new features and feature updates
- Creating a new doc vs updating an existing doc
-->
- [Feature-change documentation workflow](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages).
- [Documentation improvement workflow](improvement-workflow.md) - All documentation additions not associated with a feature release. Documentation is being created or updated to improve accuracy, completeness, ease of use, or any reason other than a feature change. Anyone (and everyone) can contribute a merge request for this type of change at any time.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7