Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
b6734b2c
Commit
b6734b2c
authored
Jun 29, 2021
by
Kati Paizee
Committed by
Suzanne Selhorn
Jun 29, 2021
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Add guidance for tutorials, get started, and resource pages in docs
parent
bb600be2
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
99 additions
and
25 deletions
+99
-25
doc/development/documentation/structure.md
doc/development/documentation/structure.md
+98
-24
doc/development/documentation/styleguide/index.md
doc/development/documentation/styleguide/index.md
+1
-1
No files found.
doc/development/documentation/structure.md
View file @
b6734b2c
...
...
@@ -19,30 +19,6 @@ 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.
GitLab also uses high-level landing pages.
## Landing pages
Landing pages are topics that group other topics and help a user to navigate a section.
Users who are using the in-product help do not have a left nav,
and need these topics to navigate the documentation.
These topics can also help other users find the most important topics
in a section.
Landing page topics should be in this format:
```
markdown
# Title (a noun, like "CI/CD or "Analytics")
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.
```
## Concept
A concept topic introduces a single feature or concept.
...
...
@@ -248,3 +224,101 @@ Consider the following guidelines when offering examples:
Although the bad-then-good approach is acceptable for the GitLab development
guidelines, do not use it for user documentation. For user documentation, use
*Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/).
## Other types of content
There are other types of content in the GitLab documentation that don't
classify as one of the four [topic types](#documentation-topic-types).
These include:
- [Tutorials](#tutorials)
- [Get started pages](#get-started)
- [Topics and resources pages](#topics-and-resources-pages)
In most cases, these content types are on their own standalone page.
### Tutorials
A tutorial is an end-to-end walkthrough of a complex workflow or scenario.
It might include tasks across a variety of GitLab features, tools, and processes.
It does not cover core conceptual information.
Tutorials should be in this format:
```
markdown
# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: create a website")
A paragraph that explains what the tutorial does, and the expected outcome.
Prerequisites (optional):
-
Thing 1
-
Thing 2
-
Thing 3
## Step 1: do the first task
To do step 1:
1.
First step.
2.
Another step.
3.
Another step.
## Step 2: do the second task
To do step 2:
1.
First step.
2.
Another step.
3.
Another step.
```
### Get started
A get started page is a set of steps to help a user get set up
quickly to use a single GitLab feature or tool.
It might consist of more than one task.
Get started pages should be in this format:
```
markdown
# Title ("Get started with <feature>")
Complete the following steps to ... .
1.
First step.
1.
Another step.
1.
Another step.
If you need to add more than one task,
consider using subsections for each distinct task.
```
### Topics and resources pages
This is a page with a list of links that point to important sections
of documentation for a specific GitLab feature or tool.
We do not encourage the use of these types of pages.
Lists like this can get out of date quickly and offer little value to users.
We've included this type here because:
- There are existing pages in the documentation that follow this format,
and they should be standardized.
- They can sometimes help navigate a complex section of the documentation.
If you come across a page like this
or you have to create one, use this format:
```
markdown
# Title ("Topics and resources for <feature>")
Brief sentence to describe the feature.
The following topics and resources can help you understand and work with this feature:
-
Link 1
-
Link 2
-
Link 3
```
doc/development/documentation/styleguide/index.md
View file @
b6734b2c
...
...
@@ -193,7 +193,7 @@ included in backticks. For example:
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
)
.
In general, we have one topic that's a
landing page
.
Below that topic in the left nav are individual topics. Each of these include a concept
and multiple related tasks, reference, and troubleshooting topics.
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment