diff --git a/source/handbook/marketing/developer-relations/technical-writing/index.html.md b/source/handbook/marketing/developer-relations/technical-writing/index.html.md index d300f840f73a654f3be7853f9bc17238759a4343..e68c2dff6d5be8fdb5860710ac499b8a222ba142 100644 --- a/source/handbook/marketing/developer-relations/technical-writing/index.html.md +++ b/source/handbook/marketing/developer-relations/technical-writing/index.html.md @@ -5,6 +5,171 @@ title: "Technical Writing" Welcome to the Technical Writing Handbook! -[Up one level to the Developer Relations Handbook](/handbook/marketing/developer-relations/) +[Up one level to the Developer Relations Handbook](../) ## On this page +{:.no_toc} + +* Will be replaced with the ToC, excluding the "On this page" header +{:toc} + +---- + +## Technical Writing + +- Introduction => to be included +- Docs and Blog Posts => to be included +- Styles Guidelines => to be included + +---- + +## 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 advices. 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 empathic 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 expertize 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 informations. + +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 the origin of officially documented information, content described in books, newspaper's articles, scientific papers, etc. + +#### 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 expertize 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 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 expertize 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_ + +---- + +## Styles Guidelines + +=> to be included from https://gitlab.com/gitlab-com/blog-posts/blob/master/STYLEGUIDE.md + + +[android-doc]: //developer.android.com/intl/pt-br/tools/help/emulator.html +[android-emulator]: //developer.android.com/intl/pt-br/tools/devices/emulator.html +[blog-tracker]: https://gitlab.com/gitlab-com/blog-posts/issues +[(key)words]: //www.wordstream.com/seo-keyword +[synonyms]: //www.thesaurus.com/ +[tech-writing-wiki]: https://en.wikipedia.org/wiki/Technical_writing + +[marketing-blog]: ../../product-marketing/content-marketing/#blog + diff --git a/source/handbook/marketing/product-marketing/content-marketing/index.html.md b/source/handbook/marketing/product-marketing/content-marketing/index.html.md index 6186c842e1e2368a0a0dc645d831bd6c12027772..517ce932ebaf1dad2e401825d4ca10bb4289ae4f 100644 --- a/source/handbook/marketing/product-marketing/content-marketing/index.html.md +++ b/source/handbook/marketing/product-marketing/content-marketing/index.html.md @@ -5,18 +5,23 @@ title: "Content Marketing" Welcome to the Content Marketing Handbook -[Up one level to the Product Marketing Handbook](/handbook/marketing/product-marketing/) +[Up one level to the Product Marketing Handbook](../) {::comment} TIP FOR ONE LEVEL UP :) {:/comment} ## On this page -* [Introduction](#intro) -* [2016 activities](#2016) -* [Webcast Overview](#webcast) -* [Scheduling webcasts](#scheduling) -* [Webcast followup](#followup) -* [Blog Overview](#blog) -* [Get published on the blog](#getpublished) -* [Blog ideas](#ideas) +{:.no_toc} +* Will be replaced with the ToC, excluding the "On this page" header +{:toc} + +{::comment} +TIP FOR TOC (KRAMDOWN): use `{:toc}` (as above) for generate the TOC AUTOMATICALLY +Use `{:.no_toc}` to EXCLUDE itemns from the TOC +{:/comment} + +{::comment} +ANCHORS: we don't need to define anchors for every heading anymore. Kramdown atributes an ID automatically :) +If we need a custom anchor => we can simply use `{: #my-custom-id}` +{:/comment} ## Introduction @@ -137,24 +142,38 @@ Check the smart list and flow first. To activate: Click the "registered" smart c - Blog post to share the recording and slides -### Viewing webcasts +### Viewing webcasts - [Citrix Online system requirements](https://support.citrixonline.com/webinar/all_files/G2W010003) - Using GoToWebinar Instant Join, Linux/Unbuntu users can view in a web browser. - Linux users should use Chromium to view the browser. +---- + +## GitLab Blog +{: #blog} + +### Objectives & Purposes -## Blog Overview +- Encourage potential users to try GitLab +- Motivate our community to explore what's best from GitLab features +- Provide accurate, interesting and new information +- MORE STUFF - MARKETING SPECIALISTS -The [blog](/blog) is our main publishing outlet. +### Important considerations -- We aim to publish content multiple times a week, with a reliable publishing -schedule -- We also want to bring in voices from all -throughout the company, as well as from GitLab users and our customers. -- Content should communicate the benefits of GitLab's unique innovations and tools (CI) +The [blog](/blog) is our main publishing outlet. Let's do our best to show what's best! + +- Content should communicate the benefits of GitLab's unique innovations and tools (e.g., CI) +- We want to bring in voices from all throughout the company, as well as +from GitLab users and our customers. +- As always, **everyone can contribute** - GitLab Team members and [Community Writers] -### Formats +### Posts Formats + +We aim to publish content multiple times a week, with a reliable publishing schedule. The user will most likely have a +pleasant experience if we combine multiple posts formats, trying never to be too much repetitive. Repetition is boring. + We'll alternate between the following formats: - Short form articles - Long form articles @@ -163,71 +182,158 @@ throughout the company, as well as from GitLab users and our customers. - Tutorials - Inside GitLab -### Product-specific topics +## Blog Content -- Tutorials on using GitLab, GitLab CI, etc. -- Feature highlights bring attention to specific features at GitLab. +It is important to have in mind that a good post can considerably reach a lot of people and acquire more users. +With well written articles, we have the opportunity to expose and explore, in a friendly language, all the features GitLab provides. -### User Stories +Try to think about what our users might have interest in reading before picking up a subject to work on. +And remember, our users do not need to be super advanced programmers. They can be newbie folks with limited experience, students, +technology enthusiasts, and people not used to Git, version control and continuous integration. That's why we need to [define a target audience][tech-writing-audience] before start writing. -* Contributor stories 'why I contribute to GitLab' -* Use case stories 'how we use GitLab' -* Boss stories 'how GitLab enabled innersourcing' -* Inception stories 'how GitLab uses GitLab' -* Adoption stories 'how we switched from SVN to GitLab' -* Customer stories 'why we choose GitLab' +Our audience will probably be interested in the topics listed below. -## Getting published on the blog +### Product-specific topics -Anyone from GitLab, Inc or within the community can propose an topic on the -GitLab [Blog Post Issue Tracker][blog-tracker]. +- Tutorials on using GitLab, GitLab CI, GitLab Runners, GitLab Geo, GitLab Pages, etc. +- Feature highlights bring attention to specific features at GitLab +- GitLab Workflow +- Key features overviews +- New feature releases -We invite guest posts and also offer compensation through the [Community Writers](https://about.gitlab.com/community/writers) program. +### User Stories -1. Submit an issue on the [Blog post issue tracker][blog-tracker]. -2. You'll get feedback on your proposal and outline. -3. Write your draft as a WIP MR (work in progress merge request) in the [GitLab website project][gitlabwww]. -4. You'll get reviewed and feedback from our editors. +- Contributor stories "why I contribute to GitLab" +- Use case stories "how we use GitLab" +- Boss stories "how GitLab enabled innersourcing" +- Inception stories "how GitLab uses GitLab" +- Adoption stories "how we switched from SVN to GitLab" +- Customer stories "why we choose GitLab" + +Do you have a better idea? Don't hesitate, [create an issue][blog-tracker] with your proposal and we'll be glad to look into it. + +### Media + +- Videos with good screencasts, great subtitles, and narratives are expensive but popular, and hard to copy (what does happens to written content). For reference, [Realm.io] does a lot of good videos, for example [about Swift] + +- Try to work with images. At least choose one for the page cover +- Do not use an image if you are not certain that it is [public domain] +- Always provide a link to the original source of the image +- Compress your image. Use [TinyPNG] or a similar tool + +## Technical Aspects + +### Publishing process for GitLab Team members + +1. Choose a [topic](#blog-content) +1. Define the target audience, knowledge level and system requirements ([example]) +1. Create outlines (a few items describing what you want to discuss along the post) +1. Submit an issue on the [blog posts issue tracker][blog-tracker] containing the previous items +1. Mention @amara for feedback on your proposal and on your outlines +1. Amara will evaluate the priority and estimate a due date for publishing +1. Write the post according to the [Professional Writing Techniques][writing-tech] +1. Submit your draft as a WIP MR (work in progress merge request) in the [GitLab website project][gitlabwww] +1. You'll get reviewed and feedback from our Marketing Team +1. Your post will be published + +Not a GitLab Team member? Check the process for [Community Writers] below. + +### Publishing process for Community Writers + +For our [community writers], we will follow the Scalable Writing System described below. + +1. Guest Writer - choose a subject: + - Make sure you are familiar with [GitLab Workflow] + - Select an issue from or create a new one. + - Leave a comment "@amara I would like to write this and I accept the terms on [Community Writers Program][I GUESS WE NEED A NEW DOC HERE]. Below follows my writing sample." +2. Content Marketing - analyse the proposal: + - Amara will evaluate the writer's sample and discuss anything necessary before start writing + - When the guest writer is approved to get started, Amara will leave a comment "@username, you got it!" and assign the issue to the writer +3. Guest Writer: prepare local environment and submit the article + - Fork and run it locally + - Write according to the [Professional Writing Techniques][writing-tech] + - Submit a [WIP MR] with the proposal and assign it to Amara +4. Reviewers: + - Amara will take a first look to approve the article for review, and assign Marcia for the first review + - When first review is finished, Marcia will assign Axil for a detailed technical review + - When finished, Axil will reassing the MR to Amara, who will follow the [check list](#check-list-before-merging) and approve the content for publishing +5. Content Marketing: publish + - Content Marketing will place the date for publishing + - Amara will merge and tweet +6. Content Marketing / Account Ops: pay the writer + - Amara email the writer to wire the money + - Guest writer will get paid + +### Blog Post Issue Tracker + +To keep things clear for everyone, we assume: + +- Anything not assigned to a person is in the [backlog] +- Anything that is assigned to a person is "in progress" +- Anything that has a WIP MR is ready for review -### About the Blog Post Issue Tracker +### Styles -- Anything not assigned to a person is in the [backlog](https://dev.gitlab.org/gitlab/blog-posts/issues?milestone_id=&scope=all&sort=created_desc&state=opened&utf8=%E2%9C%93&author_id=&assignee_id=0&milestone_title=&label_name=) -- Anything that is assigned to a person in 'in progress' -- Anything that has a WIP MR is ready for review +- Check out our [styles guidelines] +- Amuse yourself with the power of [Kramdown], our markdown engine -### Blog post publishing checklist +### Forked project -Before you write, make sure you're on a new branch cloned from master. -Check these before you publish: +Before you write, make sure you forked [`www-gitlab-com`], cloned to your computer, and were able to preview it locally by running `bundle exec middleman`. +Before making any change, create a new branch `git checkout -b branchname` cloned from `master`. -- First instance of GitLab should be linked to [GitLab](http://about.gitlab.com) -- Follow the [Blog post style guide](https://gitlab.com/gitlab-com/blog-posts/blob/master/STYLEGUIDE.md) -- Check all links. -- Check the date on the file name. -- Check the date in the post. -- Check the image is crunched down. Use [tinypng](http://tinypng.com). -- Check the blog appears good locally. -- When you have double checked, you can merge! +### Check list before merging + +Reviewer - check these before you publish: + +- First instance of GitLab should be linked to [GitLab] => WHAT EXACTLY DOES IT MEAN? +- Follow the [Blog post style guide] +- Check all links - make sure none is broken +- Check the file extension `.html.md` +- Check the date on the file name +- Check the date in the post +- Check the image(s) is(are) crunched down. +- Check the blog appears good locally +- When you have double checked, you can merge It takes about 5 mins for the blog post to appear as published. After the blog post is published we should tweet immediately from the GitLab Twitter account, and schedule follow up tweets and LinkedIn and Facebook. +## Get inspired + +- The content doesn't have to be about GitLab, it can also be other content aimed at developers, Hacker News or team leads +- You need to have high quality and high volume, great times are in the [Priceonomics content marketing handbook] +- When submitting to Hacker News please add a ? to the url and do not announce it anywhere to prevent setting off the voting ring detector +- What worked for Apigee was the 'collaboration in the 21st century' theme +- Explore a reading club such as [a NoSQL summer] +- Milk [GitLab Flow] for more blog posts and videos -## Blog ideas +## Inspire -* The content doesn't have to be about GitLab, it can also be other content aimed at developers, Hacker News or team leads. -* When submitting to Hacker News please add a ? to the url and do not announce it anywhere to prevent setting off the voting ring detector. -* You need to have high quality and high volume, great times are in the [Priceonomics content marketing handbook](http://priceonomics.com/the-content-marketing-handbook/). -* What worked for Apigee was the 'collaboration in the 21st century' theme -* Videos with good screencasts, great subtitles, and narratives are expensive but popular, and hard to copy (what does happens to written content), Realm.io does a lot of good videos, for example [about Swift](https://realm.io/news/top-5-swift-videos-of-2014/) -* A reading club such as [a NoSQL summer](http://nosqlsummer.org/) -* Milk [GitLab Flow](http://doc.gitlab.com/ee/workflow/gitlab_flow.html) for more blog posts and videos -* CI for mobile is painful (Gradle files for Android, loads of assets such as Xcode binaries) and the best current option is customizing Jenkins, mobile is a small circle that moves fast, collaborate with leading projects such as [CocoaPods](https://cocoapods.org/) for iOS (Sid can contract [Eloy Durán](https://twitter.com/alloy) and [Gradle](https://gradle.org/) for Android to create a great CI experience and blog about it -* Can accelerate the above with free CI runners -* Offer $100 per blog post and use a public issue tracker to gather idea's and tag them as acceptable. -* Encourage guest posts on our blog +We invite and encourage guest writers and also offer compensation through the [Community Writers] program. +[a NoSQL summer]: //nosqlsummer.org/ +[about Swift]: https://realm.io/news/top-5-swift-videos-of-2014/ +[backlog]: https://dev.gitlab.org/gitlab/blog-posts/issues?milestone_id=&scope=all&sort=created_desc&state=opened&utf8=%E2%9C%93&author_id=&assignee_id=0&milestone_title=&label_name= +[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]: https://about.gitlab.com/community/writers +[example]: ../../developer-relations/technical-writing/#st-subject-audience-requirements +[GitLab]: //about.gitlab.com +[GitLab Flow]: //doc.gitlab.com/ee/workflow/gitlab_flow.html +[GitLab Workflow]: https://www.youtube.com/watch?v=enMumwvLAug "Introduction to GitLab Workflow" [gitlabwww]: https://gitlab.com/gitlab-com/www-gitlab-com +[Kramdown]: //kramdown.gettalong.org/ +[Priceonomics content marketing handbook]: http://priceonomics.com/the-content-marketing-handbook/ +[public domain]: https://en.wikipedia.org/wiki/Public_domain +[Realm.io]: //realm.io +[tech-writing-audience]: ../../developer-relations/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]: ../../developer-relations/technical-writing/ +[`www-gitlab-com`]: https://gitlab.com/gitlab-com/www-gitlab-com/ + +[styles guidelines]: ../../developer-relations/technical-writing/#styles-guidelines + \ No newline at end of file