Skip to content
Snippets Groups Projects
Commit 3c8f7b11 authored by Marcia Ramos's avatar Marcia Ramos Committed by 🚄 Job van der Voort 🚀
Browse files

Move Technical Writing related handbooks to Product

parent 788eb282
Branches andrey-remove-group-caching
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 2428 additions and 2422 deletions
README.md
+ 2
− 2
View file @ 3c8f7b11
@@ -119,7 +119,7 @@ before publishing, see [**Local development**](#local-development) for
instructions.
 
[Blog Handbook]: https://about.gitlab.com/handbook/marketing/blog/
[mkd-guide]: https://about.gitlab.com/handbook/marketing/developer-relations/technical-writing/markdown-guide/
[mkd-guide]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/
 
### Adding yourself to the team page
 
@@ -312,7 +312,7 @@ follow the steps below:
[press releases]: https://about.gitlab.com/press/releases/
[press category]: https://about.gitlab.com/blog/categories/press
[blog archives]: https://about.gitlab.com/blog/archives.html
[md]: https://about.gitlab.com/handbook/marketing/developer-relations/technical-writing/markdown-guide
[md]: https://about.gitlab.com/handbook/product/technical-writing/markdown-guide
 
### Update the features page (under `/features`)
 
data/team.yml
+ 2
− 2
View file @ 3c8f7b11
@@ -909,8 +909,8 @@
twitter: XMDRamos
gitlab: marcia
maintains: |
<li><a href="/handbook/marketing/blog/community-writers/">Community Writers Program</a> Lead</li>
<li><a href="/handbook/marketing/developer-relations/technical-writing/markdown-guide/">Markdown Kramdown</a> <a href="/jobs/expert/">Expert</a></li>
<li><a href="/handbook/product/technical-writing/community-writers/">Community Writers Program</a> Lead</li>
<li><a href="/handbook/product/technical-writing/markdown-guide/">Markdown Kramdown</a> <a href="/jobs/expert/">Expert</a></li>
story: |
Marcia is passionate about computers since the early 1990s, when she first touched the
command line and somehow managed to play games on DOS. Her background in Science opened the way for technical
source/community/writers/index.html.markdown
+ 1
− 1
View file @ 3c8f7b11
@@ -8,4 +8,4 @@ suppress_header: true
 
 
The content of this page was transferred to the
[Blog Handbook - Community Writers Program](/handbook/marketing/blog/community-writers/).
[Blog Handbook - Community Writers Program](/handbook/product/technical-writing/community-writers/).
source/handbook/git-page-update/index.html.md
+ 1
− 1
View file @ 3c8f7b11
@@ -60,7 +60,7 @@ Instructions on how to update the website are in the
[readme of www-gitlab-com](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/README.md).
 
Most pages that you might want to edit are written in markdown [Kramdown](http://kramdown.gettalong.org/).
Read through our [Markdown Guide](/handbook/marketing/developer-relations/technical-writing/markdown-guide/) to understand its syntax and create new content.
Read through our [Markdown Guide](/handbook/product/technical-writing/markdown-guide/) to understand its syntax and create new content.
 
### Local Checks of Your Changes
 
source/handbook/index.html.md
+ 3
− 3
View file @ 3c8f7b11
@@ -4,7 +4,6 @@ title: Team Handbook
twitter_image: '/images/tweets/handbook-gitlab.png'
---
 
The GitLab team handbook is the central repository for how we run the company. Printed it consists of about 500 pages of text. As part of our value of being transparent the handbook is <a href="https://gitlab.com/gitlab-com/www-gitlab-com/tree/master/source/handbook">open to the world</a>, and we welcome feedback<a name="feedback"></a>. Please make a <a href="https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests">merge request</a> to suggest improvements or add clarifications.
Please use <a href="https://gitlab.com/gitlab-com/www-gitlab-com/issues">issues</a> to ask questions.
 
@@ -37,9 +36,8 @@ Please use <a href="https://gitlab.com/gitlab-com/www-gitlab-com/issues">issues<
* [UX](/handbook/ux)
* [Build](/handbook/build)
* [Marketing](/handbook/marketing)
* [Content Team](/handbook/marketing/content/)
* [Content Marketing](/handbook/marketing/content/)
* [Blog](/handbook/marketing/blog)
* [Markdown Guide](/handbook/marketing/developer-relations/technical-writing/markdown-guide/)
* [Social Marketing](/handbook/marketing/social-marketing/)
* [Social Media Guidelines](/handbook/marketing/social-media-guidelines)
* [Sales](/handbook/sales)
@@ -50,6 +48,8 @@ Please use <a href="https://gitlab.com/gitlab-com/www-gitlab-com/issues">issues<
* [Product](/handbook/product)
* [Making Gifs](/handbook/product/making-gifs)
* [Data analysis](/handbook/product/data-analysis)
* [Technical Writing](/handbook/product/technical-writing/)
* [Markdown Guide](/handbook/product/technical-writing/markdown-guide/)
 
<style>
.md-page h2 i.icon-color {
source/handbook/marketing/blog/community-writers/index.html.markdown
+ 1
− 111
View file @ 3c8f7b11
@@ -5,114 +5,4 @@ description: "Start today and earn up to $200 an article."
twitter_image: /images/handbook/marketing/community-writers-twitter-illustration.png
---
 
<br>
![Write for GitLab](/images/handbook/marketing/community-writers-twitter-illustration.png)
{::options parse_block_html="true" /}
<div class="alert alert-purple center">
## <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Get paid to write for GitLab <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{:.gitlab-orange .text-center #write-for-gitlab}
</div>
We want to publish you! **Earn up to $200 per article** writing for the [GitLab Blog].
Are you great at solving challenging problems or explaining complex ideas? Do you
have a specific area of expertise and want to share your knowledge? Help us expand
our range of tutorials and advice about creating, collaborating, and deploying with
Git and GitLab. You don't have to be an experienced writer, we will work with you
to revise, refine, and publish your post to share with our community.
## How It Works
1. Choose a topic
2. Start writing
3. Receive feedback
4. Get published
5. Get paid
All of GitLab's blog posts begin as an issue in the [GitLab blog post project][blog-project].
To become a community author:
- Select an issue from <https://gitlab.com/gitlab-com/blog-posts/issues> [labeled](#labels) with "[up-for-grabs]"
- Submit the first two paragraphs of an article or a link to a relevant article that you've written before.
- Leave a comment "@marcia I would like to write this post, and I accept the terms on the [Community Writers Program](#)"
If you don't see a topic that interests you, you can propose a new topic by
creating a new issue and following the last two instructions above. Once approved Marcia will leave a comment "@username, you got it!" and you can start writing!
## Get Paid
- In-depth tutorials or opinion pieces of 750+ words: **[USD 200.00]**
- Short tutorials of 500-750 words: **[USD 100.00]**
- [Top-priority][]: **USD 200.00**
<i class="fa fa-exclamation-triangle" aria-hidden="true" style="color: rgb(49, 112, 143);"></i>&nbsp;
Issues labeled **TOP PRIORITY**, will be compensated at **USD 200** regardless of length.
{:.alert .alert-info .text-center #top-priority}
When your post gets published, send us an invoice. GitLab will pay you in
American Dollars (USD) from a bank account in the USA, via wired transfer
to your bank account.
## Requirements
- Good written English
- Some previous experience in writing tutorials or technical overviews
- Some background on the subject you're willing to write about
- Be familiar with GitLab
## Notes
- If you want to write about your own product (or the product you represent), and how it integrates with GitLab, we'll be happy to have you as a [Guest Writer](../#guest-posts). The Community Writers Program won't apply for these cases.
- You are encouraged to write more than one post. If you succeed on the first process, we'll invite you to write for us regularly. The process for writing more than one post is exactly the same for writing the first one. Please, pick up an issue at a time.
- Your post must be original, comprehensible, technical, and unprecedented.
## Learn More
We have some standards and guidelines that need to be respected. Please make sure you're familiar with and accept them:
- [Publishing Process for Community Writers][publishing-process]
- [Blog Style Guidelines][blog-style]
- [Writing Method]
- [Markdown Guide]
<!-- identifiers -->
[avail-posts]: https://gitlab.com/gitlab-com/blog-posts/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Community+Posts&label_name%5B%5D=up-for-grabs
[blog-project]: https://gitlab.com/gitlab-com/blog-posts
[blog-style]: /handbook/marketing/blog/#styles-guidelines
[CI/CD/CD]: /2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/
[ConvDev]: /2016/09/13/gitlab-master-plan/#convdev
[Markdown Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[publishing-process]: /handbook/marketing/blog/#publishing-process-for-community-writers
[gitlab blog]: /blog/
[Pages group]: https://gitlab.com/groups/pages
[Writing Method]: /handbook/marketing/developer-relations/technical-writing/#writing-method
[topics-issues]: https://gitlab.com/gitlab-com/blog-posts/issues/
<!-- labels -->
[Community Posts]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=Community+Posts
[up-for-grabs]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=up-for-grabs
[USD 100.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24+100
[USD 200.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24200
[TOP-PRIORITY]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=TOP+PRIORITY
<style>
.center {
text-align: center;
display: block;
margin-right: auto;
margin-left: auto;
}
.alert-purple {
color: rgb(107,79,187);
background-color: #fff;
border-color: rgba(107,79,187,.5);
}
.alert-purple h2 {
margin-top: 15px;
}
</style>
This page have been [moved](/handbook/product/technical-writing/community-writers/).
source/handbook/marketing/blog/index.html.md
+ 15
− 15
View file @ 3c8f7b11
@@ -337,7 +337,7 @@ Read the section [Performing Reviews](#performing-reviews) for further details.
 
For our [community writers], we will follow the Scalable Writing System described below, coordinated by the [Blog Editorial Team].
 
1. Community Writer: detailed in [community writers program](https://about.gitlab.com/handbook/marketing/blog/community-writers/)
1. Community Writer: detailed in [community writers program](/handbook/product/technical-writing/community-writers/)
1. Content Marketing - analyses the proposal:
- Marcia will evaluate the writer's sample and discuss anything necessary before the author start writing
- If the issue isn't already labeled with the [compensation labels](#compensation-labels) (`$100`, `$200`, `TOP PRIORITY`), Marcia will define the compensation the post is worth and attribute the correct label.
@@ -958,11 +958,11 @@ To keep our blog posts consistent with one another, let's follow these simple gu
- [`categories`](#categories): use either `release` or `security release` for these posts.
 
- There are some important things to note when adding:
- [Videos](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#videos) => they must be wrapped by a `<figure>` tag with the class `video_container`, otherwise they will not look well on mobile phones. The `<figure>` tag is [very important for SEO](https://www.searchenginejournal.com/html5-an-essential-weapon-for-seos/62512/).
- [Images](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#images) => always add an `ALT` text, try to make the image filename meaningful => they will show up on Google searches more often and more accurately => again, important for SEO.
- Use [colorful sections](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#colorful-sections) to highlight the main points (use it wisely :)
- [Add `{:.shadow}` to images](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#shadow), specially GitLab UI screenshots
- Add the [class `{:.note}` for notes](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#note), instead of making them look like blockquotes, which are technically meant for quoting someone else's sayings.
- [Videos](/handbook/product/technical-writing/markdown-guide/#videos) => they must be wrapped by a `<figure>` tag with the class `video_container`, otherwise they will not look well on mobile phones. The `<figure>` tag is [very important for SEO](https://www.searchenginejournal.com/html5-an-essential-weapon-for-seos/62512/).
- [Images](/handbook/product/technical-writing/markdown-guide/#images) => always add an `ALT` text, try to make the image filename meaningful => they will show up on Google searches more often and more accurately => again, important for SEO.
- Use [colorful sections](/handbook/product/technical-writing/markdown-guide/#colorful-sections) to highlight the main points (use it wisely :)
- [Add `{:.shadow}` to images](/handbook/product/technical-writing/markdown-guide/#shadow), specially GitLab UI screenshots
- Add the [class `{:.note}` for notes](/handbook/product/technical-writing/markdown-guide/#note), instead of making them look like blockquotes, which are technically meant for quoting someone else's sayings.
 
<!-- Identifiers, in alphabetical order -->
 
@@ -979,7 +979,7 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[Blog post style guide]: https://gitlab.com/gitlab-com/blog-posts/blob/master/STYLEGUIDE.md
[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues
[Community Writers]: community-writers/
[example]: /handbook/marketing/developer-relations/technical-writing/#st-subject-audience-requirements
[example]: /handbook/product/technical-writing/#st-subject-audience-requirements
[GitLab Flow]: //doc.gitlab.com/ee/workflow/gitlab_flow.html
[GitLab Workflow]: https://www.youtube.com/watch?v=enMumwvLAug "Introduction to GitLab Workflow"
[GitLab]: /
@@ -991,10 +991,10 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[public domain]: https://en.wikipedia.org/wiki/Public_domain
[Realm.io]: //realm.io
[styles guidelines]: #styles-guidelines
[tech-writing-audience]: /handbook/marketing/developer-relations/technical-writing/#st-subject-audience-requirements
[tech-writing-audience]: /handbook/product/technical-writing/#st-subject-audience-requirements
[tinypng]: //tinypng.com
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[writing-tech]: /handbook/marketing/developer-relations/technical-writing/#professional-writing-techniques
[writing-tech]: /handbook/product/technical-writing/#professional-writing-techniques
[`www-gitlab-com`]: https://gitlab.com/gitlab-com/www-gitlab-com/
 
<!-- BLOG STYLE GUIDELINES -->
@@ -1014,12 +1014,12 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[blog]: /blog/
[bundler]: http://bundler.io/
[Chicago Manual of Style]: http://www.chicagomanualofstyle.org/home.html
[code-editors]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#markdown-editors
[code-editors]: /handbook/product/technical-writing/markdown-guide/#markdown-editors
[convox-post]: /2016/06/09/continuous-delivery-with-gitlab-and-convox/
[cross-1]: /2016/08/04/moving-to-gitlab-yes-its-worth-it/
[cross-2]: /2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/
[cross-3]: /2016/08/19/applying-gitlab-labels-automatically/
[css-shadow]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#special-classes
[css-shadow]: /handbook/product/technical-writing/markdown-guide/#special-classes
[description-tag]: http://www.wordstream.com/meta-tags
[Digital Ocean]: /2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/
[documentation]: http://docs.gitlab.com/
@@ -1036,15 +1036,15 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[Koding]: /2016/07/26/koding-and-gitlab-integrated/
[Mac screenshot]: https://support.apple.com/en-us/HT201361
[Making Gifs]: /handbook/product/making-gifs
[Markdown Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[Markdown Style Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[Markdown Guide]: /handbook/product/technical-writing/markdown-guide/
[Markdown Style Guide]: /handbook/product/technical-writing/markdown-guide/
[marketing-blog]: #blog
[Mattermost]: /2015/08/18/gitlab-loves-mattermost/
[middleman]: https://middlemanapp.com/basics/install/
[MR-description]: https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/2740/
[Nimbus Screenshot]: http://nimbus.everhelper.me/screenshot.php
[OG]: https://developers.facebook.com/docs/sharing/webmasters#markup
[outlines]: /handbook/marketing/developer-relations/technical-writing/#3rd-plan
[outlines]: /handbook/product/technical-writing/#3rd-plan
[Pivotal Cloud Foundry]: /2015/11/03/pivotal-cloud-foundry-tile-for-gitlab-ee/
[post-iOS-CI]: /2016/03/10/setting-up-gitlab-ci-for-ios-projects/
[post-lets-encrypt]: /2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/
@@ -1068,7 +1068,7 @@ To keep our blog posts consistent with one another, let's follow these simple gu
[width-post]: /2016/08/05/feature-highlight-set-dates-for-issues/
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/
[wrap text]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#wrapping-text
[wrap text]: /handbook/product/technical-writing/markdown-guide/#wrapping-text
[Yubico]: /2016/08/31/gitlab-and-yubico-security-webcast/
 
<!-- Labels -->
source/handbook/marketing/developer-relations/index.html.md
+ 1
− 2
View file @ 3c8f7b11
@@ -4,10 +4,9 @@ title: "Developer Relations"
---
# Welcome to the Developer Relations Handbook
 
The Developer Relations organization includes Developer Advocacy and Technical Writing.
The Developer Relations organization includes Developer Advocacy and Community Advocacy.
 
Developer Relations Handbooks:
 
- [Developer Advocacy](/handbook/marketing/developer-relations/developer-advocacy/)
- [Community Advocacy](/handbook/marketing/developer-relations/community-advocacy/)
- [Technical Writing](/handbook/marketing/developer-relations/technical-writing/)
source/handbook/marketing/developer-relations/technical-writing/index.html.md
+ 1
− 224
View file @ 3c8f7b11
@@ -3,227 +3,4 @@ layout: markdown_page
title: "Technical Writing"
---
 
### Welcome to the Technical Writing Handbook!
{:.no_toc}
----
## On this page
{:.no_toc}
* Will be replaced with the ToC, excluding the "On this page" header
{:toc}
----
## Technical Writing
[Technical Writers] are part of the Developer Relations Marketing Team. Their mission is to
help GitLab to:
- have all features well documented
- ensure the information regarding GitLab CE/EE/CI and its particularities are up to date
- write guides, recipes, and blog content
- assist the team with documentation and non-documentation tasks
- review every technical content published in the channels we use
[Documentation] helps the GitLab community to:
- setup and administrate their accounts
- setup and update GitLab instances
- use every tool and feature
- handle integrations, services, and tools
Docs are written technically, methodically,
programmatically, clearly, and practically.
[Blog posts][blog] have the same purpose of assisting the GitLab community,
but with a more flexible and reader-friendly language. Also,
besides the technical content, posts can be informative, tell use-case stories,
customer experience, and present a much more diverse
sort of content, since it's somehow interesting for our audience.
Whenever we write for GitLab, it's necessary to keep in mind that we are writing _on behalf_ of GitLab. We are representing the
company. Therefore, it's important to keep our personal opinions, tendencies, and point of views apart, and try to be clear, direct, concise, and professional above all. This is detailed right below, on the section [Professional Writing Techniques].
Make sure to read this through before writing for GitLab.
Also, our content is written in markdown Kramdown. Make sure to read the [Markdown Style Guide] before adventuring yourself writing for
our website [about.GitLab.com] and our [Blog], which are our "faces to the world".
On the [GitLab Blog Handbook][marketing-blog], you'll find out more about the GitLab
Blog directive, and the [Blog Style Guidelines][blog-guidelines].
## 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 and 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 some standards to follow through, for the purpose of achieving high quality work in a optimum time for conclusion.
Technical papers have the characteristic of being less personal and more formal: they're not the right place to express our opinions, nor to give advice. Accuracy matters most.
For classical scientific papers, the rules are much more restrictive and the language is absolutely formal. For blog posts, we need to use a middle term. 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 personal, depending on the subject we are writing about. In any case, though, we need to be professional. Meaning, we can be friendly and personal, but we need to focus on the point. The method suggested in this document is valid for both technical and non-technical themes, once it's related to the process of writing, not to the content itself.
Before writing on behalf of GitLab, make sure you've read through this [guide][marketing-blog].
### Technical Blog Posts
Are considered [technical][tech-writing-wiki] posts: tutorials, guides, overviews, techniques, methods, processes, and anything else which requires some sort of technical knowledge or standard procedure. For them, follow all the steps described in the [writing method](#method).
### Non-Technical Blog Posts
For non-technical post, we won't need to get into all the [steps](#method) below. Check which category matches best with the subject you'll be working on to know how to proceed.
- **Personal Experience**
- _Personal content_: user stories, user experience, opinion-based overviews and comparisons, etc.
- _Inside GitLab_
Skip the steps: [4th. Research](#th-research) and [7th. Test](#th-test).
- **Information** (If the content is not a tutorial or a guide, but it has informative purposes)
- _Feature overviews_
- _Product comparisons_
- _Case studies_
The [7th](#th-test) step can be skipped. For the [4th](#th-research) step, provide links to corroborate your information.
- **Quick Announcements**
- _Release announcements_
- _Feature highlights_
All the steps can be skipped, **except**: 1st, 6th, 8th, 9th, and 10th.
- **Other**
If your chosen subject doesn't match any previous category, read through the method, and try to use your sense to adapt it according to your case. Fell free to ask for help if needed.
### 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 to take if defining the subject, the audience, the knowledge level, and the requirements.
- Choose a subject you are very familiar with and comfortable to explain it in deep details.
- Create a title for your article, based on the previous step. A good title is very short, and accurate.
- Choose the audience:
- Who might have interest on this subject? Which instance of GitLab would be involved? GitLab EE, CE?
- What is the expertise level necessary to follow your steps? The user needs to be familiar with the subject, or comfortable with, or need to be an expert?
- What is required o make it work locally for the user? Specify the Operational System, any necessary software, any hardware condition.
- Add this information to a new issue on the [blog posts issue tracker][blog-tracker]
- Mind that you'll need to create a sentence to be included in the beginning of the article with this information. It can be explicit or subjective.
For example, for a tutorial for Android: _"We assume you know the process of creating an Android App, you already have projects running locally, and you are familiar with the GitLab UI"_. This would tell the reader that he needs to be an intermediate/advanced app developer, he/she needs to have every software necessary to run an Android application installed locally, and he/she has used GitLab before.
#### 2nd. Brainstorm
Think about everything that is possible for the subject you want to follow through. Write down every piece of information, every detail, every cool stuff that can be achieved, schemes, key processes, any knowledge that can be included in a text about your theme. Doesn't matter the order, if it's important or not, if makes absolute sense or not. Free your brain and let it work with no boundaries. Here the creativity and originality matters most.
#### 3rd. Plan
Perfect. Now you have a lot of ideas to organize. On this part you will filter the important things from your brainstorming notes, arrange them in some logic, and cut off what's not necessary. You'll do that by creating the _outlines_ for your article. Organize the headings in titles, subtitles, bullet points, brief descriptions, and include important [(key)words] that popped up into your head and you want to include in your article.
Keep in mind the audience you'd chosen before. Do not complicate things if you are writing for beginners, nor simplify too much if you're targeting advanced personal.
#### 4th. Research
Now that you know what you want to include in your paper, it's time to find reliable sources to support your scheme. You know the process, but you need to include sources for technical information.
For example, let's consider a post about Android Apps. If you say that you need an emulator for previewing your Android app locally, provide a link to the [official Android documentation][android-doc] where it's said that you need an emulator, and also add a link for the [emulator][android-emulator] itself.
Search for the sources you already know you'll need. Copy and paste the links with interesting information to a text document, or bookmark them, however you prefer. Gather the links in a way you can find them easily, to include them while you draft.
Mind that this step will end only when your post is published. You will need to come back to search for sources again and again, until the end.
A _reliable source_ is officially documented information, content described in books, newspaper's articles, scientific papers, etc. <!-- some ideas to make a better sentence here? -->
#### 5th. Draft
Now that you have a skeleton for your article, and some links to guide you through, you'll start to write, filling the gaps along the structure you'd planned before.
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 posture will avoid mistrust and lost of credibility. Follow the [Writing Tips](#writing-tips) below.
It's much quicker to write with a previous plan. Go on and write everything you need. Don't try to review every sentence or to think too much before writing down. You'll have time to review afterwards.
#### 6th. Improve
After you finished, read everything again, and see if you're not repeating yourself, or if there is some unnecessary information. Cut off everything nonessential. This will have been your first review.
After your first review, try to do other things to intentionally deviate your attention from the text. Preferably, close the file and open it just in the next day, after some sleep. This will help you to clear your head, then you'll catch mistakes you wouldn't have after several hours working on the same thing.
Now, along your second review, it's time to spot typos and grammar mistakes. Check if the text sounds clear, easy to understand and if it's not boring. Make any necessary adjustments, then start the review over again.
#### 7th. Test
If you wrote a tutorial or 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. Preferably test in as many conditions as possible: using different Operational Systems, distinct configurations, different versions, whatever applies to your case. If you have someone close to you that could contribute testing it for you too, better yet. After testing, go through the steps 4th to 6th again, if necessary.
#### 8th. Submit
When you're happy with your draft, submit it in a [WIP][WIP MR] (Work In Progress) merge request.
#### 9th. Review
Mind that your reviewers will probably ask for changes, make difficult questions, insist in some points. Do not be discouraged by the review. It will only help you to succeed even more, and to enhance the quality of your work.
If you don't agree with the reviewer at some point, just say it. Discuss your matter and defend your point of view, until you both agree with each other.
#### 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
There is a simple list below, for things to do and to avoid when writing. It's not a exact science, though. Try to balance between what's best and what's possible, be yourself, and use your sense.
- Be original: do not repeat yourself - nor repeat other posts and documentation
- Be concise: say what you need to say. Not more, nor less
- Be attentive: do not repeat the same word, use [synonyms]
- Be smart: try to predict questions - and answer them along the text
- Be precise: do not make any statement if you don't have a reliable source or the expertise to defend it
- Be clear: everything seems to be logic for whom is writing. Not necessarily for those reading
- Be organized: in tutorials, do not jump over a step presuming the audience knows that. It breaks logic and looses engrossment
- Be consistent: try to adopt patterns to facilitate the comprehension
- Be professional: prefer "it is" over "I think"
- Be inclusive: use "we" rather then "you" or "I"
- Be creative: think _out-of-the-box_ and explore things _out-of-the-blue_
----
<!-- Identifiers, in alphabetical order -->
[about.GitLab.com]: https://about.gitlab.com/
[android-doc]: http://developer.android.com/intl/pt-br/tools/help/emulator.html
[android-emulator]: http://developer.android.com/intl/pt-br/tools/devices/emulator.html
[blog]: https://about.gitlab.com/blog
[blog-guidelines]: /handbook/marketing/blog/#styles-guidelines
[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues
[bundler]: http://bundler.io/
[documentation]: http://docs.gitlab.com/
[git]: https://git-scm.com/
[issue-docs]: https://gitlab.com/gitlab-org/gitlab-ce/issues/
[(key)words]: http://www.wordstream.com/seo-keyword
[Kramdown]: http://kramdown.gettalong.org
[Mac screenshot]: https://support.apple.com/en-us/HT201361
[Markdown Style Guide]: markdown-guide/
[marketing-blog]: /handbook/marketing/blog/
[middleman]: https://middlemanapp.com/basics/install/
[Nimbus Screenshot]: http://nimbus.everhelper.me/screenshot.php
[Professional Writing Techniques]: #professional-writing-techniques
[Screenshot Tool]: https://help.ubuntu.com/lts/ubuntu-help/screen-shot-record.html
[Snipping Tool]: https://support.microsoft.com/en-us/help/13776/windows-use-snipping-tool-to-capture-screenshots
[synonyms]: http://www.thesaurus.com/
[technical aspects]: https://about.gitlab.com/handbook/marketing/product-marketing/content-marketing/#technical-aspects
[technical writers]: /jobs/technical-writer/
[tech-writing-wiki]: https://en.wikipedia.org/wiki/Technical_writing
[tinypng]: https://tinypng.com/
[unsplash]: https://unsplash.com/
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/
[Technical Writing](/handbook/product/technical-writing/) was transferred to the [Product](/handbook/product/) Team.
source/handbook/marketing/index.html.md
+ 5
− 26
View file @ 3c8f7b11
@@ -30,14 +30,12 @@ The GitLab Marketing team includes four functional groups: Demand Generation, De
- [Field Marketing]
- [Marketing Operations]
- [Online Marketing]
- [Content Marketing]
- [Design]
- [Developer Relations]
- [Developer Advocacy]
- [Community Advocacy]
- [Technical Writing]
- [Markdown Guide]
- [Product Marketing]
- [Content Team]
- [Partner Marketing]
- [Social Marketing]
- [Social Media Guidelines]
@@ -301,7 +299,7 @@ Design focuses on creating the visual brand for GitLab. Design supports product
<div class="modal-body">
<!-- EDIT FROM HERE ON LIKE NORMAL MARKDOWN -->
 
Developer Relations includes the technical writing, developer advocacy, and community advocacy functions. The team is focused on answering the following questions:
Developer Relations includes developer advocacy, and community advocacy functions. The team is focused on answering the following questions:
 
- What are scalable developer education tools?
- How do we turn in person feedback at events into actionable product requests?
@@ -335,19 +333,6 @@ What is Comm. Adv. (to be included).
[<i class="fa fa-gitlab" aria-hidden="true"></i> Matija][cmattrex]{:.btn .btn-orange}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Connor][connorshea]{:.btn .btn-orange}
 
### Technical Writing
{: .no_toc}
> _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 clear, concise, consistent, professional, and up-to-date.
[Job Description](/jobs/technical-writer/){:.btn .btn-purple-inv}
[Handbook][Technical Writing]{:.btn .btn-purple}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Axil][axil]{:.btn .btn-orange}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Marcia][marcia]{:.btn .btn-orange}
[<i class="fa fa-gitlab" aria-hidden="true"></i> Sean][sean]{:.btn .btn-orange}
<!-- DON'T EDIT THIS PART BELOW UNLESS YOU KNOW WHAT YOU'RE DOING :) -->
</div>
<div class="modal-footer">
@@ -751,35 +736,31 @@ We use our chat internally as a communication tool. The marketing channels are a
<!-- IDENTIFIERS -->
 
[cmo]: https://about.gitlab.com/jobs/chief-marketing-officer/
[create a ToC]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#table-of-contents-toc
[Markdown Style Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[techwhirl.com]: http://techwhirl.com/what-is-technical-writing/
[create a ToC]: /handbook/product/technical-writing/markdown-guide/#table-of-contents-toc
[Markdown Style Guide]: /handbook/product/technical-writing/markdown-guide/
 
<!-- HANDBOOKS -->
 
[Blog]: /handbook/marketing/blog/
[Business Development]: /handbook/marketing/demand-generation/business-development/
[Content Team]: /handbook/marketing/content/
[Content Marketing]: /handbook/marketing/content/
[Demand Generation]: /handbook/marketing/demand-generation
[Developer Advocacy]: /handbook/marketing/developer-relations/developer-advocacy/
[Community Advocacy]: /handbook/marketing/developer-relations/community-advocacy/
[Developer Relations]: /handbook/marketing/developer-relations
[Design]: /handbook/marketing/design/
[Field Marketing]: /handbook/marketing/demand-generation/field-marketing/
[Markdown Guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[Marketing Operations]: /handbook/marketing/demand-generation/marketing-operations/
[Online Marketing]: /handbook/marketing/demand-generation/online-marketing/
[Partner Marketing]: /handbook/marketing/product-marketing/partner-marketing/
[Product Marketing]: /handbook/marketing/product-marketing
[Social Marketing]: social-marketing/
[Social Media Guidelines]: /handbook/marketing/social-media-guidelines/
[Technical Writing]: /handbook/marketing/developer-relations/technical-writing/
 
<!-- Marketing Team: GitLab.com Handle -->
 
[amanda]: https://gitlab.com/u/afolson
[amara]: https://gitlab.com/u/amara
[axil]: https://gitlab.com/u/axil
[chet]: https://gitlab.com/u/chetbackman
[cmattrex]: https://gitlab.com/u/cmattrex
[connorshea]: https://gitlab.com/u/connorshea
@@ -787,10 +768,8 @@ We use our chat internally as a communication tool. The marketing channels are a
[erica]: https://gitlab.com/u/lindberg
[jennifer]: https://gitlab.com/u/jjcordz
[luke]: https://gitlab.com/u/lukebabb
[marcia]: https://gitlab.com/u/marcia
[mitchell]: https://gitlab.com/u/mitchellwright
[ryan]: https://gitlab.com/u/rycap
[sean]: https://gitlab.com/u/SeanPackham
 
<!-- EXTRA STYLES APPLIED FOR THIS PAGE ONLY -->
 
source/handbook/people-operations/functional-group-updates/index.html.md
+ 1
− 1
View file @ 3c8f7b11
@@ -87,7 +87,7 @@ Questions? Leave a comment below or tweet [@GitLab](https://twitter.com/gitlab)!
 
#### Important Notes
 
- Make sure to use correct format for [embedding videos from YouTube](/handbook/marketing/developer-relations/technical-writing/markdown-guide/#display-videos-from-youtube) into the blogpost. Replace the video URL only
- Make sure to use correct format for [embedding videos from YouTube](/handbook/product/technical-writing/markdown-guide/#display-videos-from-youtube) into the blogpost. Replace the video URL only
- Edit the video to start when the meeting actually starts:
- On YouTube, click **Edit** > **Enhancements**
- Click **trim**, then play until the part you want to split, and click **split**
source/handbook/product/technical-writing/community-writers/index.html.md 0 → 100644
+ 118
− 0
View file @ 3c8f7b11
---
layout: markdown_page
title: "Community Writers Program"
description: "Start today and earn up to $200 an article."
twitter_image: /images/handbook/marketing/community-writers-twitter-illustration.png
---
<br>
![Write for GitLab](/images/handbook/marketing/community-writers-twitter-illustration.png)
{::options parse_block_html="true" /}
<div class="alert alert-purple center">
## <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i> Get paid to write for GitLab <i class="fa fa-gitlab fa-fw" style="color:rgb(107,79,187); font-size:.85em" aria-hidden="true"></i>
{:.gitlab-orange .text-center #write-for-gitlab}
</div>
We want to publish you! **Earn up to $200 per article** writing for the [GitLab Blog].
Are you great at solving challenging problems or explaining complex ideas? Do you
have a specific area of expertise and want to share your knowledge? Help us expand
our range of tutorials and advice about creating, collaborating, and deploying with
Git and GitLab. You don't have to be an experienced writer, we will work with you
to revise, refine, and publish your post to share with our community.
## How It Works
1. Choose a topic
2. Start writing
3. Receive feedback
4. Get published
5. Get paid
All of GitLab's blog posts begin as an issue in the [GitLab blog post project][blog-project].
To become a community author:
- Select an issue from <https://gitlab.com/gitlab-com/blog-posts/issues> [labeled](#labels) with "[up-for-grabs]"
- Submit the first two paragraphs of an article or a link to a relevant article that you've written before.
- Leave a comment "@marcia I would like to write this post, and I accept the terms on the [Community Writers Program](#)"
If you don't see a topic that interests you, you can propose a new topic by
creating a new issue and following the last two instructions above. Once approved Marcia will leave a comment "@username, you got it!" and you can start writing!
## Get Paid
- In-depth tutorials or opinion pieces of 750+ words: **[USD 200.00]**
- Short tutorials of 500-750 words: **[USD 100.00]**
- [Top-priority][]: **USD 200.00**
<i class="fa fa-exclamation-triangle" aria-hidden="true" style="color: rgb(49, 112, 143);"></i>&nbsp;
Issues labeled **TOP PRIORITY**, will be compensated at **USD 200** regardless of length.
{:.alert .alert-info .text-center #top-priority}
When your post gets published, send us an invoice. GitLab will pay you in
American Dollars (USD) from a bank account in the USA, via wired transfer
to your bank account.
## Requirements
- Good written English
- Some previous experience in writing tutorials or technical overviews
- Some background on the subject you're willing to write about
- Be familiar with GitLab
## Notes
- If you want to write about your own product (or the product you represent), and how it integrates with GitLab, we'll be happy to have you as a [Guest Writer](../#guest-posts). The Community Writers Program won't apply for these cases.
- You are encouraged to write more than one post. If you succeed on the first process, we'll invite you to write for us regularly. The process for writing more than one post is exactly the same for writing the first one. Please, pick up an issue at a time.
- Your post must be original, comprehensible, technical, and unprecedented.
## Learn More
We have some standards and guidelines that need to be respected. Please make sure you're familiar with and accept them:
- [Publishing Process for Community Writers][publishing-process]
- [Blog Style Guidelines][blog-style]
- [Writing Method]
- [Markdown Guide]
<!-- identifiers -->
[avail-posts]: https://gitlab.com/gitlab-com/blog-posts/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Community+Posts&label_name%5B%5D=up-for-grabs
[blog-project]: https://gitlab.com/gitlab-com/blog-posts
[blog-style]: /handbook/marketing/blog/#styles-guidelines
[CI/CD/CD]: /2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/
[ConvDev]: /2016/09/13/gitlab-master-plan/#convdev
[Markdown Guide]: /handbook/product/technical-writing/markdown-guide/
[publishing-process]: /handbook/marketing/blog/#publishing-process-for-community-writers
[gitlab blog]: /blog/
[Pages group]: https://gitlab.com/groups/pages
[Writing Method]: /handbook/product/technical-writing/#writing-method
[topics-issues]: https://gitlab.com/gitlab-com/blog-posts/issues/
<!-- labels -->
[Community Posts]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=Community+Posts
[up-for-grabs]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=up-for-grabs
[USD 100.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24+100
[USD 200.00]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=%24200
[TOP-PRIORITY]: https://gitlab.com/gitlab-com/blog-posts/issues?label_name%5B%5D=TOP+PRIORITY
<style>
.center {
text-align: center;
display: block;
margin-right: auto;
margin-left: auto;
}
.alert-purple {
color: rgb(107,79,187);
background-color: #fff;
border-color: rgba(107,79,187,.5);
}
.alert-purple h2 {
margin-top: 15px;
}
</style>
source/handbook/product/technical-writing/index.html.md 0 → 100644
+ 233
− 0
View file @ 3c8f7b11
---
layout: markdown_page
title: "Technical Writing"
---
### Welcome to the Technical Writing Handbook!
{:.no_toc}
----
## On this page
{:.no_toc}
* Will be replaced with the ToC, excluding the "On this page" header
{:toc}
----
## 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](http://techwhirl.com/what-is-technical-writing/))
At GitLab, tech writers are the folks who take care of writing and maintaining technical content clear, concise, consistent, professional, and up-to-date.
[Technical Writers] are part of the Product Team. Their mission is to
help GitLab to:
- have all features well documented
- ensure the information regarding GitLab CE/EE/CI and its particularities are up to date
- write guides, recipes, and blog content
- assist the team with documentation and non-documentation tasks
- review every technical content published in the channels we use
[Documentation] helps the GitLab community to:
- setup and administrate their accounts
- setup and update GitLab instances
- use every tool and feature
- handle integrations, services, and tools
Docs are written technically, methodically,
programmatically, clearly, and practically.
[Blog posts][blog] have the same purpose of assisting the GitLab community,
but with a more flexible and reader-friendly language. Also,
besides the technical content, posts can be informative, tell use-case stories,
customer experience, and present a much more diverse
sort of content, since it's somehow interesting for our audience.
Whenever we write for GitLab, it's necessary to keep in mind that we are writing _on behalf_ of GitLab. We are representing the
company. Therefore, it's important to keep our personal opinions, tendencies, and point of views apart, and try to be clear, direct, concise, and professional above all. This is detailed right below, on the section [Professional Writing Techniques].
Make sure to read this through before writing for GitLab.
Also, our content is written in markdown Kramdown. Make sure to read the [Markdown Style Guide] before adventuring yourself writing for
our website [about.GitLab.com] and our [Blog], which are our "faces to the world".
On the [GitLab Blog Handbook][marketing-blog], you'll find out more about the GitLab
Blog directive, and the [Blog Style Guidelines][blog-guidelines].
## 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 and 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 some standards to follow through, for the purpose of achieving high quality work in a optimum time for conclusion.
Technical papers have the characteristic of being less personal and more formal: they're not the right place to express our opinions, nor to give advice. Accuracy matters most.
For classical scientific papers, the rules are much more restrictive and the language is absolutely formal. For blog posts, we need to use a middle term. 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 personal, depending on the subject we are writing about. In any case, though, we need to be professional. Meaning, we can be friendly and personal, but we need to focus on the point. The method suggested in this document is valid for both technical and non-technical themes, once it's related to the process of writing, not to the content itself.
Before writing on behalf of GitLab, make sure you've read through this [guide][marketing-blog].
### Technical Blog Posts
Are considered [technical][tech-writing-wiki] posts: tutorials, guides, overviews, techniques, methods, processes, and anything else which requires some sort of technical knowledge or standard procedure. For them, follow all the steps described in the [writing method](#method).
### Non-Technical Blog Posts
For non-technical post, we won't need to get into all the [steps](#method) below. Check which category matches best with the subject you'll be working on to know how to proceed.
- **Personal Experience**
- _Personal content_: user stories, user experience, opinion-based overviews and comparisons, etc.
- _Inside GitLab_
Skip the steps: [4th. Research](#th-research) and [7th. Test](#th-test).
- **Information** (If the content is not a tutorial or a guide, but it has informative purposes)
- _Feature overviews_
- _Product comparisons_
- _Case studies_
The [7th](#th-test) step can be skipped. For the [4th](#th-research) step, provide links to corroborate your information.
- **Quick Announcements**
- _Release announcements_
- _Feature highlights_
All the steps can be skipped, **except**: 1st, 6th, 8th, 9th, and 10th.
- **Other**
If your chosen subject doesn't match any previous category, read through the method, and try to use your sense to adapt it according to your case. Fell free to ask for help if needed.
### 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 to take if defining the subject, the audience, the knowledge level, and the requirements.
- Choose a subject you are very familiar with and comfortable to explain it in deep details.
- Create a title for your article, based on the previous step. A good title is very short, and accurate.
- Choose the audience:
- Who might have interest on this subject? Which instance of GitLab would be involved? GitLab EE, CE?
- What is the expertise level necessary to follow your steps? The user needs to be familiar with the subject, or comfortable with, or need to be an expert?
- What is required o make it work locally for the user? Specify the Operational System, any necessary software, any hardware condition.
- Add this information to a new issue on the [blog posts issue tracker][blog-tracker]
- Mind that you'll need to create a sentence to be included in the beginning of the article with this information. It can be explicit or subjective.
For example, for a tutorial for Android: _"We assume you know the process of creating an Android App, you already have projects running locally, and you are familiar with the GitLab UI"_. This would tell the reader that he needs to be an intermediate/advanced app developer, he/she needs to have every software necessary to run an Android application installed locally, and he/she has used GitLab before.
#### 2nd. Brainstorm
Think about everything that is possible for the subject you want to follow through. Write down every piece of information, every detail, every cool stuff that can be achieved, schemes, key processes, any knowledge that can be included in a text about your theme. Doesn't matter the order, if it's important or not, if makes absolute sense or not. Free your brain and let it work with no boundaries. Here the creativity and originality matters most.
#### 3rd. Plan
Perfect. Now you have a lot of ideas to organize. On this part you will filter the important things from your brainstorming notes, arrange them in some logic, and cut off what's not necessary. You'll do that by creating the _outlines_ for your article. Organize the headings in titles, subtitles, bullet points, brief descriptions, and include important [(key)words] that popped up into your head and you want to include in your article.
Keep in mind the audience you'd chosen before. Do not complicate things if you are writing for beginners, nor simplify too much if you're targeting advanced personal.
#### 4th. Research
Now that you know what you want to include in your paper, it's time to find reliable sources to support your scheme. You know the process, but you need to include sources for technical information.
For example, let's consider a post about Android Apps. If you say that you need an emulator for previewing your Android app locally, provide a link to the [official Android documentation][android-doc] where it's said that you need an emulator, and also add a link for the [emulator][android-emulator] itself.
Search for the sources you already know you'll need. Copy and paste the links with interesting information to a text document, or bookmark them, however you prefer. Gather the links in a way you can find them easily, to include them while you draft.
Mind that this step will end only when your post is published. You will need to come back to search for sources again and again, until the end.
A _reliable source_ is officially documented information, content described in books, newspaper's articles, scientific papers, etc. <!-- some ideas to make a better sentence here? -->
#### 5th. Draft
Now that you have a skeleton for your article, and some links to guide you through, you'll start to write, filling the gaps along the structure you'd planned before.
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 posture will avoid mistrust and lost of credibility. Follow the [Writing Tips](#writing-tips) below.
It's much quicker to write with a previous plan. Go on and write everything you need. Don't try to review every sentence or to think too much before writing down. You'll have time to review afterwards.
#### 6th. Improve
After you finished, read everything again, and see if you're not repeating yourself, or if there is some unnecessary information. Cut off everything nonessential. This will have been your first review.
After your first review, try to do other things to intentionally deviate your attention from the text. Preferably, close the file and open it just in the next day, after some sleep. This will help you to clear your head, then you'll catch mistakes you wouldn't have after several hours working on the same thing.
Now, along your second review, it's time to spot typos and grammar mistakes. Check if the text sounds clear, easy to understand and if it's not boring. Make any necessary adjustments, then start the review over again.
#### 7th. Test
If you wrote a tutorial or 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. Preferably test in as many conditions as possible: using different Operational Systems, distinct configurations, different versions, whatever applies to your case. If you have someone close to you that could contribute testing it for you too, better yet. After testing, go through the steps 4th to 6th again, if necessary.
#### 8th. Submit
When you're happy with your draft, submit it in a [WIP][WIP MR] (Work In Progress) merge request.
#### 9th. Review
Mind that your reviewers will probably ask for changes, make difficult questions, insist in some points. Do not be discouraged by the review. It will only help you to succeed even more, and to enhance the quality of your work.
If you don't agree with the reviewer at some point, just say it. Discuss your matter and defend your point of view, until you both agree with each other.
#### 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
There is a simple list below, for things to do and to avoid when writing. It's not a exact science, though. Try to balance between what's best and what's possible, be yourself, and use your sense.
- Be original: do not repeat yourself - nor repeat other posts and documentation
- Be concise: say what you need to say. Not more, nor less
- Be attentive: do not repeat the same word, use [synonyms]
- Be smart: try to predict questions - and answer them along the text
- Be precise: do not make any statement if you don't have a reliable source or the expertise to defend it
- Be clear: everything seems to be logic for whom is writing. Not necessarily for those reading
- Be organized: in tutorials, do not jump over a step presuming the audience knows that. It breaks logic and looses engrossment
- Be consistent: try to adopt patterns to facilitate the comprehension
- Be professional: prefer "it is" over "I think"
- Be inclusive: use "we" rather then "you" or "I"
- Be creative: think _out-of-the-box_ and explore things _out-of-the-blue_
----
<!-- Identifiers, in alphabetical order -->
[about.GitLab.com]: https://about.gitlab.com/
[android-doc]: http://developer.android.com/intl/pt-br/tools/help/emulator.html
[android-emulator]: http://developer.android.com/intl/pt-br/tools/devices/emulator.html
[blog]: https://about.gitlab.com/blog
[blog-guidelines]: /handbook/marketing/blog/#styles-guidelines
[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues
[bundler]: http://bundler.io/
[documentation]: http://docs.gitlab.com/
[git]: https://git-scm.com/
[issue-docs]: https://gitlab.com/gitlab-org/gitlab-ce/issues/
[(key)words]: http://www.wordstream.com/seo-keyword
[Kramdown]: http://kramdown.gettalong.org
[Mac screenshot]: https://support.apple.com/en-us/HT201361
[Markdown Style Guide]: markdown-guide/
[marketing-blog]: /handbook/marketing/blog/
[middleman]: https://middlemanapp.com/basics/install/
[Nimbus Screenshot]: http://nimbus.everhelper.me/screenshot.php
[Professional Writing Techniques]: #professional-writing-techniques
[Screenshot Tool]: https://help.ubuntu.com/lts/ubuntu-help/screen-shot-record.html
[Snipping Tool]: https://support.microsoft.com/en-us/help/13776/windows-use-snipping-tool-to-capture-screenshots
[synonyms]: http://www.thesaurus.com/
[technical aspects]: https://about.gitlab.com/handbook/marketing/product-marketing/content-marketing/#technical-aspects
[technical writers]: /jobs/technical-writer/
[tech-writing-wiki]: https://en.wikipedia.org/wiki/Technical_writing
[tinypng]: https://tinypng.com/
[unsplash]: https://unsplash.com/
[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request"
[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/
source/handbook/product/technical-writing/markdown-guide/html5-demo.mp4 0 → 100644
+ 0
− 0
View file @ 3c8f7b11
File added
source/handbook/product/technical-writing/markdown-guide/index.html.md 0 → 100644
+ 2034
− 0
View file @ 3c8f7b11
This diff is collapsed.
source/posts/2016-01-26-call-for-writers.html.md
+ 3
− 3
View file @ 3c8f7b11
@@ -6,7 +6,7 @@ author_twitter: nearlythere
image_title: '/images/blogimages/write-gitlab.jpg'
---
 
Update: Please see our updated [Community Writers Program](https://about.gitlab.com/handbook/marketing/blog/community-writers/)
Update: Please see our updated [Community Writers Program](https://about.gitlab.com/handbook/product/technical-writing/community-writers/)
 
We’re opening our blog up to contributions from the community.
When you get published on our blog at [GitLab](https://about.gitlab.com/blog) you can earn $50 to $200 for technical articles.
@@ -37,7 +37,7 @@ What we're looking for...
- In-depth tutorials or opinion pieces of 1,500+ words.
 
 
Review [our call for writers](/community/writers) for the kinds of topics we're looking for.
Review [our call for writers](/handbook/product/technical-writing/community-writers/) for the kinds of topics we're looking for.
 
## New to GitLab? That's OK!
 
@@ -71,4 +71,4 @@ These are some ideas our team have in their wishlist. Do you see something you c
1. Publish.
1. Get paid.
 
Visit [our call for writers](/community/writers) for more information on how to get started.
Visit [our call for writers](/handbook/product/technical-writing/community-writers/) for more information on how to get started.
source/posts/2016-07-19-markdown-kramdown-tips-and-tricks.html.md
+ 6
− 6
View file @ 3c8f7b11
@@ -414,13 +414,13 @@ Follow [@GitLab] and stay tunned for the next post!
 
[about.GitLab.com]: /
[@GitLab]: https://twitter.com/GitLab
[boxes]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#colorful-sections
[classes]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#classes-ids-and-attributes
[boxes]: /handbook/product/technical-writing/markdown-guide/#colorful-sections
[classes]: /handbook/product/technical-writing/markdown-guide/#classes-ids-and-attributes
[CodePens]: https://codepen.io
[contribute]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/CONTRIBUTING.md
[docs]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#embed-documents
[docs]: /handbook/product/technical-writing/markdown-guide/#embed-documents
[font awesome]: http://fontawesome.io/
[guide]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/
[guide]: /handbook/product/technical-writing/markdown-guide/
[Handbook]: /handbook/
[handbook-post]: /2016/07/12/our-handbook-is-open-source-heres-why/
[identifier]: #
@@ -431,9 +431,9 @@ Follow [@GitLab] and stay tunned for the next post!
[news]: https://news.ycombinator.com/item?id=12091638
[responsive]: https://css-tricks.com/NetMag/FluidWidthVideo/Article-FluidWidthVideo.php
[SSGs]: /2016/06/10/ssg-overview-gitlab-pages-part-2/
[videos]: /handbook/marketing/developer-relations/technical-writing/markdown-guide/#videos
[videos]: /handbook/product/technical-writing/markdown-guide/#videos
[www-GitLab-com]: https://gitlab.com/gitlab-com/www-gitlab-com
[source file]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/source/handbook/marketing/developer-relations/technical-writing/markdown-guide/index.html.md
[source file]: https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/source/handbook/product/technical-writing/markdown-guide/index.html.md
 
<style>
.blue {
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment