Technical Writing

Welcome to the Technical Writing Handbook!

On this page

Technical Writing

Technical writing is sometimes defined as simplifying the complex. In a concise and deceptively simple definition, it is a whole range of skills and characteristics that address nearly every field of human endeavor at some level. (techwhirl.com)

At GitLab, tech writers are the folks who take care of writing and maintaining technical content, while keeping it clear, concise, consistent, professional, and up-to-date.

Technical Writers are part of the Product Team. Their mission is to help GitLab by:

Documentation helps the GitLab community to:

Docs are written technically, methodically, programmatically, clearly, and practically.

Blog posts have the same goal of assisting the GitLab community as documentation, but with a more natural and reader-friendly language. Also, besides technical content, posts can be informative, tell use-case stories, relay customer experiences, and present a much more diverse selection of content, since they are designed to be interesting to our audience.

Whenever we write for GitLab, it's necessary to keep in mind that we are writing on GitLab's behalf. We are representing the company. Therefore, it's important to keep our personal opinions, biases, and points of view separate, and always be clear, direct, concise, and above all professional. This is detailed below, in Professional Writing Techniques. Make sure to read this through before writing for GitLab.

Also, our content is written in markdown Kramdown. Be sure to read the Markdown Style Guide before venturing into writing for our website about.GitLab.com or our Blog, which are our "faces to the world".

On the GitLab Blog Handbook, you'll find out more about the GitLab Blog directive, and the Blog Style Guidelines

Workflow

In order to be organized and provide timely documentation with every feature release, a standard workflow (process) is required.

Read how the Docs team flows.

Markdown Style Guide for about.GitLab.com

Check out our Markdown Style Guide for the markup used throughout about.GitLab.com, including any markdown page or blog post. You'll find useful information there, some Kramdown magic, and it might save you a lot of typing.

Professional Writing Techniques

When writing professionally, it's important to understand and follow some standards, for the purpose of achieving high quality work in an optimal time frame.

Technical papers have the characteristic of being less casual and more formal; they're not the right place to express opinions, nor to give advice. Accuracy is what matters most. For scientific papers, the rules are even more restrictive and the language is strictly formal.

For blog posts, we need to find a middle ground. Be clear, precise, and professional, but be empathetic and "reader-friendly". A discrete and occasional touch of humor is also welcome.

When writing non-technical blog posts, we can be less formal and more casual, depending on the subject we are writing about. Regardless, we need to continue being professional. This means we can be friendly and personal, but we need to focus on the point. The methods suggested in this document are valid for both technical and non-technical topics in regards to the process of writing, not to the content itself.

Before writing on behalf of GitLab, make sure you've read through this guide.

Technical Blog Posts

Technical posts include: tutorials, guides, overviews, techniques, methods, processes, and anything else which requires some sort of technical knowledge or standard procedure. For these cases, follow all the steps described in the writing method.

Non-Technical Blog Posts

For non-technical posts, we don't need to do every step in the writing method below. Check which category matches best with the subject you'll be working on to know how to proceed.

Writing Method

The following method suggests steps to take in order to create high quality written productions. This approach is recommended, but flexible. Feel free to adapt it to your needs.

1st. Subject, Audience, Requirements

The first step is to define the subject, the audience, the knowledge level, and the requirements.

2nd. Brainstorm

Think about everything regarding the subject you want to write about. Write down every piece of information, every detail, every cool thing that can be achieved, every scheme, key process, or knowledge that could be included in an article about your topic. Don't worry about the order, if it's important or not, or if it makes perfect sense or not. Free your brain and let it work with no boundaries. Here, creativity and originality matters most.

3rd. Plan

Perfect. Now you should have a lot of ideas to organize. In this stage you will filter out the important things from your brainstorming notes, arrange them in a logical order, and cut out what's not necessary. You'll do that by creating the outlines for your article. Organize the sections with titles, subtitles, bullet points, brief descriptions, and include important (key)words that came out in the brainstorming that you want to include in your article.

Keep in mind the audience you chose before. Do not complicate things if you are writing for beginners, or simplify too much if you're targeting experts.

4th. Research

Now that you know what you want to include in your article, it's time to find reliable sources to support it. You may know the process, but you still need to include sources for technical information.

For example, let's consider a post about Android Apps. If you write that you need an emulator to preview your Android app locally, you should provide a link to the official Android documentation where it's explained that an emulator is needed, and also add a link to the emulator itself.

Search for the sources you already know you'll need. Copy and paste the links to key information into a text document or bookmark them, however you prefer. Gather the links in such a way that you can find them easily, to include them while you draft.

Be aware that this step will end only when your post is published. You will need to come back and search for sources again and again, until the end.

A reliable source is officially documented information, as well as content described in books, newspaper articles, scientific papers, etc.

5th. Draft

Now that you have a skeleton for your article, and some links to guide you, you can start to write, filling in the gaps following the structure you planned in step 3.

Never make a statement without providing the source for that information, unless it is your own conclusion and you have the expertise to defend it. This way of writing will avoid mistrust and loss of credibility. Follow the Writing Tips below.

It's much quicker to write with a clear plan. Contiinue and write everything you need. Don't try to review every sentence or think too much before writing it down. You'll review afterwards.

6th. Improve

After you finished step 5, read everything again, and make sure you're not repeating yourself, and that there is no unnecessary information. Cut out everything non-essential. This is the first review.

After your first review, try to do other things to intentionally deviate your attention from the text. Preferably, close the file and only open it the next day, after some sleep. This will help you clear your head, which will help you find mistakes you wouldn't have caught even after several hours working on the same thing.

Now, during your second review, it's time to look for typos and grammar mistakes. Check that the text is clear, easy to understand and that it's not boring. Make any necessary adjustments, then do another review.

7th. Test

If you wrote a tutorial or about any procedure that can be tested, test it. Go over your steps exactly as you described them, and check if you succeed following your own steps. Testing in as many conditions as possible is preferred: different Operational Systems, configurations, versions, or whatever applies to your case. If you have someone close to you that could contribute by testing it for you too, that's even better. After testing, go through steps 4 to 6 again, if necessary.

8th. Submit

When you're happy with your draft, submit it in a WIP (Work In Progress) merge request.

9th. Review

Be aware that your reviewers will probably request changes, ask difficult questions, insist on some points. Do not be discouraged by the review. It will only help you to improve it even more, and enhance the quality of your work.

If you don't agree with the reviewer about something, just say it (respectfully). Discuss your matter and defend your point of view, until you both agree or find a compromise.

10th. Publish

After you adjust the post according to the reviewers' requests, it will get published and everybody will be happy for you!

Writing Tips

This is a simple list, for things to do and avoid when writing. It's not an exact science, though. Try to find a balance between what's best and what's possible. Be yourself and use your own judgement.

Staying up to date

You are not expected to know everything, but it is essential to stay on top of things. Collaborating with the other groups is very important for learning about what features will be released and what resources are needed from your side.

Some tips: