IAM A Writer
Hello! My name is Christer and I'm the Technical Advocate here at IAM Pulse. Part of my job is to collect and curate IAM resources from around the Internet. This often means working with people to write down what they know and share the knowledge and wisdom they've gained in the trenches of IAM.
I'm also here is to facilitate learning and fostering an environment where members can grow their skillset. To that end we've adopted a framework for documentation that is aimed at the learning process.
The standard for technical documentation we selected is based on the Diataxis
documentation framework. If you're new to technical writing you'll find this a great reference for structuring your future content!
The framework has been described as the “The Grand Unified Theory of
Documentation” and applies to all types of technical material. The principles apply to the type and style of content on our platform, helping those that are learning to solve real-world problems. The four styles of content described don’t enforce strict writing restrictions but rather provide you with guidance to focus on the goal of conveying useful information.
At IAM Pulse we believe that one of the problems in this space is a knowledge gap. IAM for the cloud is a complex and far reaching issue. I totally get it if you don't feel like you *really* understand it. Neither do I!
This is why I like the Diataxis framework for documentation. It's less about a rigorous structure for writing as it is a framework for understanding technical writing. I want to help you make sure the reader gets as much out of the content as they can. Improving and fostering the learning process for our readers is top priority.
Following this framework will result in your readers learning more and coming
away feeling better for having read it. Lift as you climb.
With that in mind here are some tips and benefits for planning future content.
Determining your format
Before you begin writing an article it is important to define which of the four content 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)
Remember, 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 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.
Did you know that writing can advance your career and provide opportunities for you? The StackOverflow Blog described ways in which writing can advance your career as a developer.
If you're looking to advance your career through writing you're in the right
place. We're always on the lookout for new authors, fresh content and new
insightful ways to think about IAM.
Please reach out if you're the type of person who enjoys writing technical
documentation! I'm happy to work with you to publish existing content or
to brainstorm content ideas related to IAM. Our content is as diverse as our
community and I'm sure you'd be a great fit to join our list of authors!
I'm excited to be a part of the IAM Pulse team and look forward to working with
you to create a beneficial learning environment.
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.