Style guide

Posted Jan 1, 2025

laptop and a cup of coffee

By Charity Fretty

1 min read

A style guide for my work at Minnesota IT Services partnering with Minnesota Pollution Control Agency (MNIT MPCA).

This guide provides editorial guidelines for writing technical documentation at MNIT MPCA. The topics here are guidelines, not rules. It’s OK to break them if it will make your content simpler, clearer, or more accurate.

This guide is a supplement, not a comprehensive writing style guide. Add information here when primary references don’t provide explicit guidance. Technical documentation is different than marketing or other communications. Here are considerations and exceptions for technical information and MNIT MPCA products.

Plain language

Before you start and while you are writing, use plain language.

Use plain language - 18F Content Guide

Plain Language Writing and Editing- LinkedIn Learning

plainlanguage.gov

Plain Language resources - Digital.gov

Voice and tone

Be conversational, friendly, and respectful. Above all, be clear and accurate. Technical information must be trustworthy: reliable and correct. Being precise, helpful, and concise is more important than being creative.

Our style - 18F Content Guide

Our standards for quality tech doc

Audience oriented. Know your audience and their needs. State your audience in your deliverable: “This guide is for role(s) who responsibilities….”

Task oriented. Not all topics are step-by-step procedures, but you can write all topics to help the audience do their work.

Applies minimalism.

Is DRY (Don’t repeat yourself). Document once, use (or refer) everywhere.

When possible, topic-based and structured.

See “Principles of good technical documentation.”

The page continues, listing the style resources (internal and external) and which order to use them. Then specific guidelines, such as word choices.