mjpagan/technical-writing-for-cloudskills-community

Guidelines and the process for contributing to the community blogs

Technical Writing for the CloudSkills Community

Creating content for the CloudSkills.io blog is a rewarding opportunity available to all CloudSkills community members. It's not only a great way to build upon your career, but also to share what you know with the IT community.

In this guide, you will find information on how to get started blogging for CloudSkills.io. Followed by the steps to having your blog published on multiple channels.

Blogging requirements and compensation

All blog contributions should meet the following requirements:

• Minimum of 1000 words. 1500-2000 is preferable.

• Contributions must be written in Markdown.

• Content can be anything cloud-related, however, no technologies like Office365.

Compensation will be discussed after the first post is submitted. The first post is seen as a "trial". Instead of a fixed set price for blog posts, compensation is based on the level of writing of each author and will start after the first initial blog post.

Process

It's your first time writing a blog for CloudSkills.io? We've set out a simple process for all contributors to follow. This is to ensure content is on the right topics, is high quality and is consistent in how it is published.

Step 1 - Email Mike a blog summary

All content for CloudSkills.io runs through Mike, if you are thinking along the Blogging Requirements guidelines above for content, you should be pretty much there. Put a summary together for your idea and email it over to Mike. If you're not sure, email it anyway or put it up for discussion in Slack. Another community member can likely help with finding a slant that fits the blogging requirements.

Once Mike has OK'd the content, you're good to go with pulling the full post together.

Step 2 - Grab the markdown template and create your content

For now, we are following the template outline for blog formatting from Digital Ocean. In the future, we will make our own format and template, but for now, reference Digital Ocean's Technical Writing Guidelines and Technical Best Practices. Within the Digital Ocean Technical Writing Guidelines is a link to their Markdown Template, copy the template and use it as your base.

Checkout Useful Tools at the bottom of these guidelines for VSCode extensions to help with Markdown and online writing quality checkers.

Tip - number your images by step and position within the step, for example "step1-1-azure-devops-pipeline.png". This should help a part of make Step 7 a little easier until we automate it.

Step 3 - Email Mike for a GitHub invite and push up your repo

The CloudSkills Community content is held alongside this repo on the CloudSkills GitHub Org. You'll need to ask Mike for an invite before you can push up your repo. Once you've accepted the invite, create a new repo in the CloudSkills Org and push it up.

Step 4 - Content review

Once your repo is in the GitHub org, drop Mike a message. The submitted content is then reviewed by other community contributors for grammatical errors and technical clarity.

This is another great way to get involved in contributing to the community blogs. Reviewing opportunities from a technical standpoint or for content clarity are available. If you are interested in reviewing, drop Mike a message.

Step 5 - Headshot and biography

You'll need a bio and headshot for the author's page. Get this together while your content is being reviewed and email it over to Mike.

Step 6 - Post published on CloudSkills.io

Finally, your blog is published on the CloudSkills.io blog. Great job!

Once a post is published, it is customary for CloudSkills community contributors to share and re-post each other's content across Linkedin and Twitter social media networks. This increases the view count of everyone's content and becomes more powerful as the CloudSkills contributor base increases.

Step 7 - Convert your content for dev.to

Once the article goes live on CloudSkills.io. You will want to upload the post to dev.to. Follow the instructions on how to upload your post to the dev.to platform.

Step 8 - What if it's a blog series

Each part of the series will be published separately as this should increase the view count if compared to posting a full series at once. You have the choice of pushing all series parts at once to the repo, or across a small time frame. If you do choose to push the parts separately, each part will go through the same process, Push, Review, Publish, Convert to Dev.to.

If you choose to push each part separately, please keep the content in one repo, but split out the images and markdown files between the series parts. For example:

This will make it easier to convert into a blog at CloudSkills.io.

Useful Tools

Here are two VSCode extensions that provide a great Markdown editing experience. Alternatively, you can run Josh Duffney's PowerShell gist to automatically install these extensions along with some useful Azure extensions:

• Docs Markdown Extension

• Docs Authoring Pack

Your blog post will be checked for grammatical errors, but it's good to run a few checks of your own, this will also help to grow good habits if you are new to writing. Examples that other contributors use are:

• Grammarly - Spelling and grammar

• Hemmingway Editor - Sentence structure and writing clarity

FAQ

What if I'm not very skilled at writing? Writing is a skill, and everyone starts at the beginning. Don't let it hold you back. Your posts will be reviewed by someone for grammatical errors and feed back. If you're still unsure about your writing ability. Reach out on the #builders channel in slack and see if anyone would like to Co-Author a blog post with you to help get you started.

I just started my Azure learning journey, should I wait until I ramp up on Azure to blog? NO! Everyone, no matter what level they are at, has something valuable to share. No matter where you are at skill wise there are thousands of people that are at a lower level and could benefit from your point of view. Blogging is also a great way to increase knowledge of a subject and is an excellent form of learning.

I hate writing, is there something else I can do? There are other opportunities to contribute to the CloudSkills community other than writing. Reach out to Mike for other area's you may be able to help with. But it is highly encouraged to try writing a blog post at least once if you haven't had the experience yet. You might end up enjoying it :-).

I'm having trouble finding ideas to blog about Take some time to think about what you can write about that would be valuable for someone else to know. Brainstorm and write your ideas down. If you're still having trouble, reach out on the #builders channel in slack and explain what area you would like to write about and if anyone has ideas.

I've been reworking and reworking, how do I get out of this loop To quote Jeffrey Snovar - To ship is to choose. Even if your content isn't perfect in your eyes, it's important to get content out there. Once you do this and repeat, and repeat again, you may find you are over thinking it. If you are still unsure, slack and the review process are there to help you out!