Commit 2d98443d authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Susan Tacker

Add topic types

parent 4297c0c2
......@@ -12,7 +12,7 @@ The GitLab documentation is [intended as the single source of truth (SSOT)](http
In addition to this page, the following resources can help you craft and contribute to documentation:
- [Style Guide](styleguide/index.md) - What belongs in the docs, language guidelines, Markdown standards to follow, links, and more.
- [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one.
- [Topic type template](structure.md) - Learn about the different types of topics.
- [Documentation process](workflow.md).
- [Markdown Guide](../../user/markdown.md) - A reference for all Markdown syntax supported by GitLab.
- [Site architecture](site_architecture/index.md) - How <https://docs.gitlab.com> is built.
......
......@@ -5,167 +5,165 @@ info: To determine the technical writer assigned to the Stage/Group associated w
description: What to include in GitLab documentation pages.
---
# Documentation structure and template
# Documentation topic types
Use these standards to contribute content to the GitLab documentation.
At GitLab, we have not traditionally used topic types. However, we are starting to
move in this direction, and we now use four topic types:
Before getting started, familiarize yourself with [Documentation guidelines for GitLab](index.md)
and the [Documentation Style Guide](styleguide/index.md).
- [Concept](#concept)
- [Task](#task)
- [Reference](#reference)
- [Troubleshooting](#troubleshooting)
## Components of a documentation page
Each page contains multiple topic types. For example,
a page with the title `Pipelines`, which is generated from a file called `index.md`,
can include a concept and multiple task and reference topics.
Most pages are dedicated to a specific GitLab feature or to a use case that
involves one or more features, potentially in conjunction with third-party tools.
GitLab also uses high-level landing pages.
In general, each topic should include the following content, in this sequence:
## Landing pages
- *Metadata*: Information about the stage, group, and how to find the technical
writer for the topic. This information isn't visible in the published help.
- *Title*: A top-level heading with the feature or use case name. Choose a term
that defines the functionality and use the same term in all the resources
where the feature is mentioned.
- *Introduction*: In a few sentences beneath the title, describe what the
feature or topic is, what it does, and in what context it should be used.
- *Use cases*: Describe real user scenarios.
- *Prerequisites*: Describe the software, configuration, account, permissions,
or knowledge required to use this functionality.
- *Tasks*: Present detailed step-by-step instructions on how to use the feature.
- *Troubleshooting*: List errors and how to address them. Recommended but not
required.
Landing pages are topics that group other topics and help a user to navigate a section.
You can include additional subsections, as appropriate, such as *How it Works*,
or *Architecture*. You can also include other logical divisions, such as
pre-deployment and post-deployment tasks.
Users who are using the in-product help do not have a left nav,
and need these topics to navigate the documentation.
## Template for new docs
These topics can also help other users find the most important topics
in a section.
Follow the [folder structure and filename guidelines](styleguide/index.md#folder-structure-overview)
and create a new topic by using this template:
Landing page topics should be in this format:
```markdown
<!--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. This information is displayed
in Google Search snippets. It may help to write the page intro first, and then reuse it here.
stage: Add the stage name here
group: Add the group name here
info: To determine the technical writer assigned to the Stage/Group associated with this page,
see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Title (a noun, like "CI/CD or "Analytics")
# Feature or Use Case Name **[TIER]** (1)
<!--If you are writing about a use case, start with a verb,
for example, "Configure", "Implement", + the goal/scenario-->
Brief introduction to the concept or product area.
Include the reason why someone would use this thing.
- Bulleted list of important related topics.
- These links are needed because users of in-product help do not have left navigation.
```
<!--For pages on newly-introduced features, add the following line.
If only some aspects of the feature have been introduced, specify which parts of the feature.-->
> [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2).
## Concept
Write a description of the feature or use case. This introduction should answer
these questions:
A concept topic introduces a single feature or concept.
- 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 or
requirements?
- What can the audience do with this? (Be sure to consider all applicable
audiences, such as GitLab admin and developer-user.)
- What are the benefits of using this over any existing alternatives?
A concept should answer the questions:
You can reuse this content, or part of it, for the front matter's `description`
at the top of this file.
- What is this?
- Why would I use it?
## Use cases
Think of everything someone might want to know if they’ve never heard of this topic before.
Describe common use cases, typically in bulleted form. Include real-life examples
for each.
Don’t tell them **how** to do this thing. Tell them **what it is**.
If the page itself is dedicated to a use case, this section usually includes more
specific scenarios for use (for example, variations on the main use case), but if
that's not applicable, you can omit this section.
If you start describing another topic, start a new concept and link to it.
Concept topics should be in this format:
```markdown
# Title (a noun, like "Widgets")
Examples of use cases on feature pages:
A paragraph that explains what this thing is.
- 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](../../administration/geo/index.md)
- EE-only: [Jenkins integration](../../integration/jenkins.md)
Another paragraph that explains what this thing is.
## Prerequisites
Remember, if you start to describe about another concept, stop yourself.
Each concept topic should be about one concept only.
```
State any prerequisites for using the feature. These might include:
## Task
- Technical prereqs (for example, an account on a third-party service, an amount
of storage space, or prior configuration of another feature)
- Prerequisite knowledge (for example, familiarity with certain GitLab features
or other products and technologies).
A task topic gives instructions for how to complete a procedure.
Link each one to an appropriate place for more information.
Task topics should be in this format:
## Tasks
```markdown
# Title (starts with an active verb, like "Create a widget" or "Delete a widget")
Each topic should help users accomplish a specific task.
Do this task when you want to...
The heading should:
Prerequisites (optional):
- Describe the task and start with a verb. For example, `Create a package` or
`Configure a pipeline`.
- Be short and descriptive (up to ~50 chars).
- Start from an `h2` (`##`), then go over `h3`, `h4`, `h5`, and `h6` as needed.
Never skip a hierarchy level (like `h2` > `h4`). It breaks the table of
contents and can affect the breadcrumbs.
- Thing 1
- Thing 2
- Thing 3
Bigger tasks can have subsections that explain specific phases of the process.
To do this task:
Include example code or configurations when needed. Use Markdown to wrap code
blocks with [syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting).
1. Location then action. (Go to this menu, then select this item.)
1. Another step.
1. Another step.
Example topic:
Task result (optional). Next steps (optional).
```
## Create a teddy bear
Here is an example.
Create a teddy bear when you need something to hug. (Include the reason why you
might do the task.)
```markdown
# Create an issue
To create a teddy bear:
Create an issue when you want to track bugs or future work.
1. Go to **Settings > CI/CD**.
1. Expand **This** and click **This**.
1. Do another step.
Prerequisites:
The teddy bear is now in the kitchen, in the cupboard above the sink. _(This is the result.)_
- A minimum of Contributor access to a project in GitLab.
You can retrieve the teddy bear and put it on the couch with the other animals. _(These are next steps.)_
To create an issue:
Screenshots are not necessary. They are difficult to keep up-to-date and can
clutter the page.
1. Go to **Issues > List**.
1. In the top right, click **New issue**.
1. Complete the fields. (If you have a reference topic that lists each field, link to it here.)
1. Click **Submit issue**.
<!-- ## Troubleshooting
The issue is created. You can view it by going to **Issues > List**.
```
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 documentation comments with questions that you know
someone might ask.
## Reference
Each scenario can be a third-level heading, for example, `### 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. -->
A reference topic provides information in an easily-scannable format,
like a table or list. It's similar to a dictionary or encyclopedia entry.
---
```markdown
# Title (a noun, like "Pipeline settings" or "Administrator options")
Notes:
Introductory sentence.
- (1): Apply the [tier badges](styleguide/index.md#product-badges) accordingly.
- (2): Apply the correct format for the
[GitLab version that introduces the feature](styleguide/index.md#gitlab-versions-and-tiers).
| Setting | Description |
|---------|-------------|
| **Name** | Descriptive sentence about the setting. |
```
## Help and feedback section
## Troubleshooting
Troubleshooting topics can be one of two categories:
- **Troubleshooting task.** This topic is written the same as a [standard task topic](#task).
For example, "Run debug tools" or "Verify syntax."
- **Troubleshooting reference.** This topic has a specific format.
Troubleshooting reference topics should be in this format:
```markdown
# Title (the error message or a description of it)
You might get an error that states <error message>.
This issue occurs when...
The workaround is...
```
## Other information on a topic
Topics include other information.
For example:
- Each topic must have a [tier badge](styleguide/index.md#product-tier-badges).
- New topics must have information about the
[GitLab version where the feature was introduced](styleguide/index.md#where-to-put-version-text).
### Help and feedback section
This section ([introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/319) in GitLab 11.4)
is displayed at the end of each document and can be omitted by adding a key into
......@@ -180,7 +178,7 @@ feedback: false
The default is to leave it there. If you want to omit it from a document, you
must check with a technical writer before doing so.
### Disqus
#### Disqus
We also have integrated the docs site with Disqus (introduced by
[!151](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/151)),
......@@ -206,7 +204,7 @@ The click events in the feedback section are tracked with Google Tag Manager.
The conversions can be viewed on Google Analytics by navigating to
**Behavior > Events > Top events > docs**.
## Guidelines for good practices
### Guidelines for good practices
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36576/) in GitLab 13.2 as GitLab Development documentation.
......
......@@ -15,9 +15,7 @@ For guidelines specific to text in the GitLab interface, see the Pajamas [Conten
For information on how to validate styles locally or by using GitLab CI/CD, see [Testing](../testing.md).
Use this guide for standards on grammar, formatting, word usage, and more.
You can also view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style&not[label_name][]=docs%3A%3Afix).
You can view a list of [recent updates to this guide](https://gitlab.com/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=tw-style&not[label_name][]=docs%3A%3Afix).
If you can't find what you need:
......@@ -31,10 +29,8 @@ If you have questions about style, mention `@tw-style` in an issue or merge requ
## Documentation is the single source of truth (SSOT)
### Why a single source of truth
The documentation of GitLab products and features is the SSOT for all
information related to implementation, usage, and troubleshooting. It evolves
The GitLab documentation is the SSOT for all
information related to GitLab implementation, usage, and troubleshooting. It evolves
continuously, in keeping with new products and features, and with improvements
for clarity, accuracy, and completeness.
......@@ -44,7 +40,7 @@ about GitLab products.
It also informs decisions about the kinds of content we include in our
documentation.
### All information
### The documentation includes all information
Include problem-solving actions that may address rare cases or be considered
_risky_, but provide proper context through fully-detailed
......@@ -54,10 +50,13 @@ If you think you have found an exception to this rule, contact the
Technical Writing team.
GitLab adds all troubleshooting information to the documentation, no matter how
unlikely a user is to encounter a situation. For the [Troubleshooting sections](#troubleshooting),
people in GitLab Support can merge additions themselves.
unlikely a user is to encounter a situation.
### All media types
GitLab Support maintains their own
[troubleshooting content](../../../administration/index.md#support-team-docs)
in the GitLab documentation.
### The documentation includes all media types
Include any media types/sources if the content is relevant to readers. You can
freely include or link presentations, diagrams, and videos. No matter who
......@@ -71,48 +70,33 @@ include it.
quotation with the source cited. Typically it is better to either rephrase
relevant information in your own words or link out to the other source.
### No special types
### Topic types
In the software industry, it is a best practice to organize documentation in
different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/):
- Tutorials
- How-to guides
- Explanation
- Reference (for example, a glossary)
At GitLab, we have so many product changes in our monthly releases that we can't
afford to continuously update multiple types of information. If we have multiple
types, the information becomes outdated. Therefore, we have a
[single template](../structure.md) for documentation.
GitLab documentation does not distinguish specific document types. We are open to
reconsidering this policy after the documentation has reached a future stage of
maturity and quality. If you are reading this, then despite our continuous
improvement efforts, that point hasn't been reached.
### Link instead of summarize
different types. For example:
There is a temptation to summarize the information on another page, which
causes the information to live in two places. Instead, link to the single source
of truth and explain why it is important to consume the information.
- Concepts
- Tasks
- Reference
- Troubleshooting
### Organize by topic, not by type
At GitLab, we have not traditionally used topic types. However, we are starting to
move in this direction, so we can address these issues:
We organize content by topic, not by type, so it can be located in the
single-source-of-truth (SSOT) section for the subject matter. Top-level audience-type
folders, like `administration`, are exceptions.
- **Content is hard to find.** Our docs are comprehensive and include a large amount of
useful information. Topic types create repeatable patterns that make our content easier
to scan and parse.
- **Content is often written from the contributor's point of view.** Our docs
are written by contributors. Topic types (tasks specifically) help put
information into a format that is geared toward helping others, rather than
documenting how a feature was implemented.
For example, do not create groupings of similar media types. For example:
GitLab uses these [topic type templates](../structure.md).
- Glossaries.
- FAQs.
- Sets of all articles or videos.
### Link instead of repeating text
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 (for example, everything related to CI goes together) and
cross-link between any related content.
Rather than repeating information from another topic, link to the single source
of truth and explain why it is important.
### Docs-first methodology
......@@ -127,14 +111,9 @@ of GitLab more efficient.
should be to create a merge request (MR) to add this information to the
documentation. You can then share the MR to communicate this information.
New information about the future usage or troubleshooting
of GitLab should not be written directly in a forum or other messaging system.
Instead, add it to a documentation merge request, then reference it. Note
that among any other documentation changes, you can either:
- Add a [Troubleshooting section](#troubleshooting) to a doc if none exists.
- Un-comment and use the placeholder Troubleshooting section included as part of
our [documentation template](../structure.md#template-for-new-docs), if present.
New information that would be useful toward the future usage or troubleshooting
of GitLab should not be written directly in a forum or other messaging system,
but added to a documentation MR and then referenced, as described above.
The more we reflexively add information to the documentation, the more
the documentation helps others efficiently accomplish tasks and solve problems.
......@@ -217,8 +196,11 @@ included in backticks. For example:
## Structure
Because we want documentation to be a SSOT, we should [organize by topic, not by
type](#organize-by-topic-not-by-type).
We include concept and task topic types in the same larger topic.
In general, we have one topic that's a [landing page](../structure.md#landing-pages).
Below that topic in the left nav are individual topics. Each of these include a concept
and multiple related tasks, reference, and troubleshooting topics.
### Folder structure overview
......@@ -299,7 +281,7 @@ place for it.
### Avoid duplication
Do not include the same information in multiple places.
[Link to a single source of truth instead.](#link-instead-of-summarize)
[Link to a single source of truth instead.](#link-instead-of-repeating-text)
### References across documents
......@@ -966,8 +948,8 @@ this option.
## Links
Links are important in GitLab documentation. They allow you to [link instead of
summarizing](#link-instead-of-summarize) to help preserve a [single source of truth](#why-a-single-source-of-truth)
Links are important in GitLab documentation. Use links instead of
summarizing to help preserve a [single source of truth](#documentation-is-the-single-source-of-truth-ssot)
in GitLab documentation.
We include guidance for links in these categories:
......@@ -1895,21 +1877,6 @@ In this case:
- Use the [GitLab Restart](#gitlab-restart) section to explain any required
restart or reconfigure of GitLab.
### Troubleshooting
For troubleshooting sections, provide as much context as possible so
users can identify their problem and resolve it on their own. You
can facilitate this by making sure the troubleshooting content addresses:
1. The problem the user needs to solve.
1. How the user can confirm they have the problem.
1. Steps the user can take towards resolution of the problem.
If the contents of each category can be summarized in one line and a list of
steps aren't required, consider setting up a [table](#tables). Create headers of
_Problem_ \| _Cause_ \| _Solution_ (or _Workaround_ if the fix is temporary), or
_Error message_ \| _Solution_.
## Feature flags
Learn how to [document features deployed behind flags](../feature_flags.md). For
......
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