diff options
Diffstat (limited to 'doc/development/documentation/topic_types/task.md')
-rw-r--r-- | doc/development/documentation/topic_types/task.md | 68 |
1 files changed, 65 insertions, 3 deletions
diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 0dba3e079b6..8d23a5f322e 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -45,7 +45,7 @@ To create an issue: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Issues > List**. -1. In the top right corner, select **New issue**. +1. In the upper-right corner, select **New issue**. 1. Complete the fields. (If you have reference content that lists each field, link to it here.) 1. Select **Create issue**. @@ -57,8 +57,70 @@ The issue is created. You can view it by going to **Issues > List**. For the title text, use the structure `active verb` + `noun`. For example, `Create an issue`. -If you have several tasks on a page that share prerequisites, you can use the title -`Prerequisites` and link to it. +If several tasks on a page share prerequisites, you can create a separate +topic with the title `Prerequisites`. + +### When more than one way exists to perform a task + +If more than one way exists to perform a task in the UI, you should +document the primary way only. + +However, sometimes you must document multiple ways to perform a task. +When this situation occurs: + +- Introduce the task as usual. Then, for each way of performing the task, add a topic title. +- Nest the topic titles one level below the task topic title. +- List the tasks in descending order, with the most likely method first. +- Make the task titles as brief as possible. When possible, + use `infinitive` + `noun`. + +Here is an example. + +```markdown +# Change the default branch name + +You can change the default branch name for the instance or group. +If the name is set for the instance, you can override it for a group. + +## For the instance + +Prerequisites: + +- You must have at least the Maintainer role for the instance. + +To change the default branch name for an instance: + +1. Step. +1. Step. + +## For the group + +Prerequisites: + +- You must have at least the Developer role for the group. + +To change the default branch name for a group: + +1. Step. +1. Step. +``` + +### To perform the task in the UI and API + +Usually an API exists to perform the same task that you perform in the UI. + +When this situation occurs: + +- Do not use a separate heading for a one-sentence link to the API. +- Do not include API examples in the **Use GitLab** documentation. API examples + belong in the API documentation. If you have GraphQL examples, put them on + their own page, because the API documentation might move some day. +- Do not mention the API if you do not need to. Users can search for + the API documentation, and extra linking adds clutter. +- If someone feels strongly that you mention the API, at the end + of the UI task, add this sentence: + + `To create an issue, you can also [use the API](link).` ## Task introductions |