Content Submission Guide

Helpful and prescriptive guidance for writing and publishing content for our article catalog to be shared with the community

Our community platform is centered around semi-structured technical content, which we refer to as an Article. We want to give our authors the flexibility to create content in their own style with their own voice, while also making each contribution reference-able and usable by others.

Article Format

  • Information: Title, subtitle, banner image, and URL (optional if referencing a public repo or other website)
  • Environment: selected attributes that describe the technical elements of the article content (see below for list)
  • Markdown: freeform text, code, and images explaining the use case, relevant context, historical findings, and more.

Publishing Instructions

Only community members can publish Articles on the site. When logged in, you can open up the Publishing Wizard at any time by clicking 'New' in the navbar. This will start a new Draft Article. Follow along these steps to create and submit a new Article.

Step 1: Article Information

Publishing Wizard Step 1

First things first, give your article a title and subtitle. Try to be descriptive and punchy with the title, you can add more expansive context in the subtitle. You'll add tags in the next step for things like cloud providers and code frameworks, but it's a good practice to mention what this article is for in the title/subtitle – i.e. Terraform on AWS.

We want to give you the opportunity to promote any associated external links and/or preserve your SEO goodness if this content was originally published elsewhere. Both fields are optional – URL will display a link at the top of the article when displayed, and Canonical URL will place a meta tag in the article source. They don't have to be the same link – i.e. you can link out to a GitHub repo and have the meta tag point to your personal blog.

The cover image serves 2 purposes – it's displayed as the card image in list views and social sharing, as well as the full width cover background on the article page. The choice is yours – you can grab an image from a stock photo website, take a screenshot of your template example, or go full abstract! If you don't supply a cover image, we'll choose one on your behalf.

Step 2: Environment Attributes

Publishing Wizard Step 2

Select all of the relevant attributes of your article to help describe how and where your content can be leveraged. You can choose multiple options for each category, or leave blank if there's no associated attribute.

Step 3: Article Markdown

Publishing Wizard Step 3

Last step! Here's where rubber meets the road – time to get your article crafted. We've built a nice Markdown editor so you can write your post in an easy to understand manner. We support all of the most common Markdown formats, plus a couple of custom block types for our Images and Code Blocks. If you’ve written a README on GitHub before, this will be quite familiar. If not, check out this helpful Markdown reference guide.

You can add images at any point while writing. Simply drag & drop your image, or copy and paste it directly into the editor, and the image will be automatically uploaded and added inline.

At any time during your editing, you can toggle between the Markdown Editor and a Preview display to see how the markdown is being converted. For a complete Preview of what your article will look like on the frontend website, click the 'full page preview' button at the top.

When you are done and ready to submit your article, select the 'Submit' button. This will put your article into a moderated state, sending our Moderators a notification that the article is ready to be reviewed. You will also get an email notification that your article is in review. We may reach out to you to ask any clarifying questions or make edit suggestions. When your article has been reviewed, we'll send you another email notification with a link to the published article and a virtual kudos for a job well done!

Get the IAM Pulse Check Newsletter

We send out a periodic newsletter full of tips & tricks, contributions from the community, commentary on the industry, relevant social posts, and more.

Checkout past issues for a sampling of the goods.