GitLab Technical Writing, 23 Jun 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Session 3 Tech Writing Fundamentals

Description

Reviews even more grammar and style requirements and linting. More information:
https://about.gitlab.com/handbook/engineering/ux/technical-writing/fundamentals/

A

This is session three of get lab technical writing fundamentals. We are going to pick up where we left off at the end of session two looking at a table that is not parallel. This table is from the style, guide, the documentation, style guide and the second column under what belongs here. The entries are not parallel.

A

First, entry starts with a compound adjective.

A

Second, entry starts with the noun compound adjective noun adjective verb verb noun, since most of these start with a noun we're going to edit to make them consistent and parallel.

A

We changed user related documentation to documentation for users.

A

Now all the entries in the table start with a noun, except for legal documents about contributing to gitlab. I could not come up with an edit, a quick edit for that. That was uh not awkward, so left that one alone, I changed the heading. What belongs here to contents and because these change, it's better than it was we do iterative changes, went ahead and merged.

A

Documentation also needs to avoid promises that a task is easy or simple, because it might not be to the person who is reading the documentation and attempting to perform the task.

A

Instead of you can easily configure your server to send email simply tell people how to do it to configure your server to send email complete the following steps.

A

We get a lot of questions about hyphenation, particularly for a feature called the to-do list in the phrase to do in the term. To-Do list to do is a compound adjective modifying the word list, so it's hyphenated.

A

If you were to say I have a to do, that's a noun and we don't hyphenate nouns in that form.

A

I have a to do, is rather awkward, so we suggest using to do items and, if you'll note, to do modifies items. So it's hyphenated.

A

The documentation style guide for get lab contains almost all of the information that we have gone over in these sessions and there is a link here, so you can go check it out.

A

Some other high level suggestions are use. We for recommendations, not git lab recommends, but we recommend it's okay to use contractions.

A

We use they as a singular pronoun, because that's inclusive language, an example of that is pat needs help. They can't do it alone and we avoid wordiness we edit for wordiness. If a sentence has more than 25 words, it's too long. The fastest way to make a topic more readable is to write in shorter sentences.

A

So how do we test for all of the things that we have talked about? We use linting.

A

The pipeline includes markdown lint and veil, documentation tests, markdown, lint checks for formatting and veil checks for language for markdown lit all the issues break the pipeline and you have to go fix it. However, in veil there are three levels of suggestion and only errors break the pipeline.

A

We have a lot of information about the testing that we do at the included link in the third bullet. So I hope you can check it out.

A

Our next session is going to cover concepts, tasks, references and troubleshooting topics, so see you. There.