GitLab Technical Writing, 23 Jun 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Session 2 Tech Writing Fundamentals

Description

Session 2 reviews additional grammar and style requirements.

More information:
https://about.gitlab.com/handbook/engineering/ux/technical-writing/fundamentals/

A

Hey there, this is the second recording in the series, technical writing fundamentals at gitlab. I hope that you have completed the pre-class material for the google technical writing 1 class, as well as the intro video for this class.

A

We're going to cover in this section the first half of our topics about how we write and our first guideline is. We use consistent terminology if you're going to name a thing, use that name consistently pick one term and use it every time, for example, in the sentence, use an environment variable for your ci job environment. Variable is a thing. The next sentence says these cicd variables work with jobs to populate values at runtime.

A

It seems to mean that cicd variables are the same thing as an environment variable, but it's not 100 clear.

A

So a better option is pick a term use. It consistently use the cicd variable for your ci job. These cicd variables work with ci jobs to populate values at runtime.

A

Our second guideline is about using active voice instead of passive voice. Technical writing should primarily use active voice. It's more easily comprehended actor plus verb plus target is the way these sentences are arranged for active voice, the technical writer who's, the actor rights, that's the verb, the documentation, the technical writer writes the documentation.

A

That is an active sentence.

A

In active voice, the actor comes first in passive voice. The target may come first, the value is calculated well. The question for that sentence is by what the value is calculated by the algorithm answers. The question, but it's still passive active voice would reframe the sentence to the algorithm calculates the value.

A

So let's try this out.

A

In the sentence when engineers attempt something new and innovative, a reward should be given. If I were an engineer, I would want to know by whom.

A

So a possible edit would be when engineers attempt something new and innovative. We should give them a reward that answers the question. However, a better sentence is when engineers innovate. We should reward them new and innovative, as a phrase is redundant.

A

A guideline that we're going to talk about a little later is to remove unnecessary words.

A

Also in active voice, you can keep an eye out for words that end in ed. They can signify passive voice. For example, the code is interpreted by python. The active sentence would be python interprets the code.

A

We also use present tense in gitlab documentation, as well as in the get lab ui.

A

It's just another way that we make sentences more direct and more immediate, so future tense is. When you select the option, the widget will start the test. Now, grammatically, that's correct, but it's future tense present tense would be when you select the option. The widget starts the test.

A

Our next guideline is about knowing the difference between ordered and unordered lists. Ordered lists are in order, so they're numbered one. Two, three, four, five, six unordered lists use bullets.

A

The order of items in an unordered list doesn't matter, but in all list items at get lab. You start with a capital letter.

A

You can use unordered lists or bulleted lists instead of long sentences. In this example, you can migrate from bitbucket cloud bitbucket server, clearcase, github and sbn.

A

But a better version would be you can migrate from and then list these in bullet items. This is easier to scan a sentence. A long sentence using lots of commas is not as easy to scan and comprehend as a bulleted list, and we want our users to be able to scan topics to find what they're looking for.

A

Now, in any list, we want parallel structure because it helps with comprehension, so we start and end all all bullet items. Similarly, if you start the first bullet with a verb start, the last bullet with a verb read the paper wash the dog throw out the starting pitch. Excuse me: you will also see that those three bullets all end in a period, so you use a colon after the intro stem, so in our example start and end all bullets. Similarly, similarly is followed by a colon.

A

That's the intro stem to the following bullets.

A

We don't use commas or semicolons at the end of list items we do add periods to the end of list items when the item consists of a complete sentence with a subject and a verb or if the item completes a sentence, that's begun in the introductory stem.

A

And you want to be consistent if the majority of the items end with a period end them all with the period and likewise for if they don't end in a period.

A

So here's an example for parallel structure.

A

In what belongs here, the list, these items- start user, related documentation, documentation that requires the user api related documentation, documentation, related legal documents contains instructions. Suddenly we have an item that starts with a verb and the following one does as well in a table like this. The descriptions should all start. Similarly,.

A

We're going to stop here for this session and we will begin in the next video the rest of our topics.