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 blog post. The first blog post is a trial for CloudSkills to see your writing style. If anything needs to be changed or altered, we'll let you know and give you tops.

After that, all blog posts are $100.00 per 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 A Blog Summary to Mike and Michael

All content for CloudSkills.io runs through Mike and Michael, if you are thinking along the Blogging Requirements guidelines above for content, you should be pretty much there.

Put the idea in an email and send it over. 3-4 lines on the idea will work.

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 Levan for a GitHub invite and create your branch

The CloudSkills Community content is held in the posts repo which sits alongside this repo on the CloudSkills GitHub Org. You'll need to ask Mike for an invite before you can create your branch. Once you've accepted the invite, clone your repo and create a branch, use a standard branch naming convention such as:

git branch /users/stevensnicole/gitdevops-getting-started
git checkout /users/stevensnicole/gitdevops-getting-started

If this is your first blog, you'll need to create a folder under posts to group all of your content, this folder should be your github username or your name. Under your user folder, each post needs it's own folder, even if it's a multi-part blog. An example of how this could look over time:

/posts
    /stevensnicole
        /git-1-getting-started-with-git
        /git-2-working-with-pull-requests-azuread
        /git-3-creating-a-build-pipeline-aspnetcode
        /docker-java-azure-sql-webapp
        /git-4-merging

Once your post is written and commited locally, push your branch up to the posts repo:

git push origin /users/stevensnicole/gitdevops-getting-started

Step 4 - Pull request and content review

Create a pull request for your branch in GitHub, this will trigger the review process. The submitted content is reviewed by other community contributors for grammatical errors and technical clarity. A standard PR process is followed, required changes are passed back as PR comments to be reviewed and updated by the author. Once the review passed, the PR is merged and the blog is ready to post.

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 in Slack.

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!