COMING SOON!! We're just getting started, so we haven't launched our community site yet, but you can subscribe by email to get updates on our progress, and a first look at what we're building. Join our waitlist here:
Our community platform is centered around semi-structured technical content, which we refer to as a Template. 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.
The community platform – currently in development – supports self-publishing of Templates through a guided wizard. While still in development, the IAM Pulse team will collaborate with authors in an ad-hoc manner to draft contributions ready to be published when the site is launched.
Metadata: Title, subtitle, banner image, and URL (optional if referencing a public repo or other website)
Topics: selected attributes that describe the technical elements of the template content (see below for list)
Article: markdown copy of freeform text explaining the use case, relevant context, historical findings, and more.
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.
Images: complementary images such as reference architecture diagrams or screenshots. Each image includes a short text caption.
List of Topics
Each contributed template should be marked with the following attributes as it relates to the content. You can select many attributes for each topic, or skip over if generic or irrelevant.
This framework has been described as the “The Grand Unified Theory of Documentation”. These principles apply to the type and style of content on our platform. Beneficial both to those that are learning and industry professionals working to solve real-world problems. These four styles of content don’t force strict writing restrictions but rather provide you with guidance to focus on the goal at hand.
Determining your format
Before you begin writing your Template it is important to define which of the four types best apply. Ask yourself what it is you’re trying to accomplish with this content.
Are you trying to teach a specific skill? (tutorial)
Is this content for beginners (tutorial) or helpful to an industry professional? (how-to)
Do you want to guide someone to solve or avoid a problem? (how-to)
Attempting to describe an infrastructure, code or API? (reference)
Write an article about the history and evolution of the industry? (explanation)
Making Content Work
These guidelines are here to help you succeed in writing the best content you can!
Defining the content style that best suites the message or information you’re trying to communicate is a critical step. Knowing the best suited style tells you what to focus on and what to avoid when writing. It helps you define clear distinctions and separations for the type of information you should and shouldn’t include. By defining the scope and the goal of your content it simplifies knowing what to write and how to write it. Well written content that follows these guidelines becomes a useful and shareable resource online benefiting learners and professionals in their journey.
Readers benefit from these principles by understanding what information they’re going to gain and what to expect from the content. The information is more easily absorbed and retained and the reader leaves feeling benefited having read it. Each of these types of content are key to different stages in the learning process and provide the reader with progressive benefits as their understanding evolves.
For some additional guidance, check out a few outlines we’ve prepared that give that little nudge to get you on your way. We don’t expect you to follow these to a “t”, but they can be helpful getting that first word on the screen... we’ve all stared at an empty doc before, so we know :)