GitLab GitLab Technical Writing Fundamentals, 24 Jun 2021

Previous Meeting

Next Meeting

⏯

youtube image

►

From YouTube: Session 4 Tech Writing Fundamentals

Description

Reviews topic types: concepts, tasks, references, troubleshooting (CTRT).

A

Hey y'all, this is session four of git lab technical writing fundamentals and in this session we are going to talk about topic types concept, task, reference, troubleshooting or ctrt topic types.

A

So why do we need to organize information in different kinds of topic types? Well, first, the human brain is a pattern recognizer.

A

When we organize information consistently people begin to recognize the patterns that we use and begin to understand what kind of information it is that we're presenting.

A

These four topic types are an industry standard. There are companies that enforce these topic types pretty rigidly, we don't and consistency can help. People learn how to use our documentation.

A

Our docs often start in a first draft by describing the feature that was coded, but eventually our documentation has to be presented from the user's perspective and topic types help us do that.

A

So here are the definitions of what we call ctrt a concept explains a feature or process and why you use it, it gives some context.

A

A task leads the user through a procedure, almost always a numbered list of steps.

A

A reference topic can list settings or options or parameters and includes their definitions, often presented in a table and a troubleshooting topic uses either tasker reference format to assist the user. When things go wrong,.

A

So, let's dig in a little bit a concept again introduces a single feature or idea. It answers the questions. What is this, why would I want to use it and optionally? When would I not use this concept feature or idea?

A

The format is a noun title like widgets and a paragraph or two that explains what this thing is, and here is a good example of a concept pipelines for merge requests.

A

It's a noun title.

A

We always talk about when a feature is introduced introduced in gitlab 11.6.

A

In a basic configuration, gitlab runs a pipeline each time changes are pushed to a branch. If you want the pipeline to run jobs only on commits associated with the merge request, you can use pipelines for merge requests. So we talk about what it is and when to use it with more additional information.

A

A task provides instructions about how to complete a procedure, how to do something. It answers the questions. How do I use this and it uses numbered lists.

A

The format of a task is, it starts with an active verb like create a widget. We don't use creating a widget. The correct title would be create a widget and it tells the users why they would want to do this task. What's the context we have found from user research that our customers want context around features and tasks.

A

You can list prerequisites, and here is the format to do whatever to create a widget.

A

You provide the location in the application in the get lab application and then the action, and then you list the steps that people need to take to complete this task. You can also give the result and the next steps.

A

And here is a really good example prevent members from being added to a group. As a group owner, you can prevent any new project membership for all projects in a group allowing tighter control over project membership. That gives some context and it gives an example.

A

Then the format for the task is to prevent members from being added to a group. Colon go to the group's settings general page. This is the correct format for how to do something in gitlab.

A

It also lists the result.

A

A reference topic provides information in a scannable format like a table or a list. You can think of a dictionary or encyclopedia entry. When you think about reference topics, reference topics are additional information.

A

The format is again a noun pipeline setting pipeline settings or administrator options and an introductory sentence like use these settings to configure your pipelines. There is no colon to introduce a table, and then you have your table.

A

And here is an example: this is a unordered list.

A

The get lab conan repository supports the following cli commands and lists the commands with the definition from our earlier session. You'll also note that the definitions are parallel. Upload install search view, delete.

A

Troubleshooting tasks can be excuse me, troubleshooting topics can be either tasks or reference depends on the information that you want to provide.

A

Here is one with a reference format, a title: you would use the whole error message, a portion of it or a description of the error. This makes the information that you're, providing in this troubleshooting topic findable makes it easier to find in a search.

A

You might get an error that states error message you talk about when the issue occurs and you give a workaround.

A

So here's a good example error running yarn with the package registry for npm registry.

A

It shows the error message and it gives some troubleshooting advice. What to try.

A

Troubleshooting topics help you fix things.

A

So to see additional examples of ctrt structure, you can see our documentation topic types page in the style guide and we also provide a topic about editing content into different topic types. That shows you examples of editing.

A

If you have any questions about any of the sessions that we have provided, let us know there is a an issue available to you for feedback in the technical writing project and there's a link here, thanks for joining.

A