Content Submission Guide
Helpful and prescriptive guidance for writing and publishing content in our 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.
- 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)
- Diagrams: complementary images such as reference architecture diagrams or screenshots. Each image includes a short text caption.
- Code Blocks: sample code snippets – can be a json policy, bash script, Terraform module, etc. Each code block includes a single code snippet and markdown docs for reference.
- Markdown: freeform text explaining the use case, relevant context, historical findings, and more.
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
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
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: Related Diagrams
Upload any Images to be referenced in your article. These can be architecture diagrams, screenshots, or flow diagrams that relate to your content. Optionally give each uploaded Image a text caption.
When you get to the markdown section of this wizard, all uploaded Images will be easily referenced, so you can drop them inline your markdown copy. We carve out Images as a dedicated content type to display a dedicated Image Gallery on the published article.
Step 4: Associated Code Blocks
This section is where you can add individual code blocks to be referenced in your article. These can be policy documents, infrastructure code samples, or bash scripts for example.
Provide a filename and choose a language, purely for the reader's reference, not necessarily an explicit file. The Code Block has an independent text area for the code itself and any respective documentation. Docs are optional, but it's recommended to write explicit docs for each code block if there are implementation steps to consider, variables to substitute, etc.
You can add as many Code Blocks as you'd like here. When you get to the markdown section of this wizard in the next step, all Code Blocks will be easily referenced by filename, so you can drop them inline your markdown copy. Just like with Images, we carve out Code Blocks as a dedicated content type to display independently on the published article.
Step 5: Article Markdown
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.
Any Images and/or Code Blocks you added in the previous steps will be listed to the right of the editor. At any point in writing, simply select which Image or Code Block you want to insert, and it'll drop in a custom Markdown block. As the hint suggests, don't edit the text that gets placed. The key is a reference for our CMS, which loads the respective Image or Code Block.
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.