Sections & navigation
Writing for Different Content Types
A recipe, an email, a personal essay, and a reference article ask different things of a writer. Start with what readers need, then choose a structure and tone that serve that purpose.
This section covers everyday messages, articles, and instructions. The optional practical references cover more specialized guides and product writing when you need them.
10.1Instructions and Reference Writing
Help readers understand a subject or complete a task. Choose between a walkthrough, a quick reminder, and a detailed guide based on what they already know.
10.1.1Getting-Started Guides
Show a beginner the essential first steps. Explain what they need before they begin and what they should be able to do afterward.
Keep the scope manageable. A short guide to planting herbs does not need to cover every aspect of gardening.
10.1.2Quick Reference Guides
Provide a reminder for someone who already knows the basics. A checklist, table, or short list may work better than several paragraphs.
Example: A packing list for a weekend trip.
Keep the information easy to scan without removing details that affect the meaning.
10.1.3Longer Guides
Organize a detailed guide around the reader’s questions. Use descriptive headings, a clear sequence, and navigation that helps readers return to a specific topic.
Introduce unfamiliar ideas before relying on them. Keep background information distinct from steps the reader needs to follow.
Installation and Setup GuidesOptional reference
10.2Configuration Guides
A setup guide helps someone get a tool ready to use. Explain what they’ll need, which choices they can make, and how they’ll know they’re ready.
10.2.1Installation Guides
- Focus on environment setup, system requirements, and initial installation steps.
- Include prerequisites, commands, and platform-specific instructions.
- Use numbered steps and visuals where helpful.
10.2.2Setup Guides
- Provide post-installation setup instructions (e.g., first-time login, initial configurations).
- Include tips for optional settings and integrations.
- Address common errors or missteps.
Troubleshooting and Support WritingOptional reference
10.3Helping Readers Solve Problems
When someone is stuck, help them find a sensible next step. Explain the problem in recognizable terms and let them check one possibility at a time.
10.3.1Working Through a Problem
Start with what the reader can observe, then work from simple checks to more involved ones. Explain what each result means and where it leads.
Example: If the headphones work with another device, check the sound settings on this one.
Put any risk or consequence before an action. A small decision diagram can help when several paths branch.
10.3.2Product Manuals
- Combine user instructions, technical references, and support information.
- Provide both high-level overviews and detailed sections.
- Suitable for more technical or complex products.
10.4Articles and Everyday Communication
Use the format that fits the message. Give readers a clear opening, enough context, and a useful sense of what comes next.
10.4.1Informational Articles
Answer a clear question or explain a focused subject. Introduce the main point early, then build on it with useful context and examples.
Use headings when they help readers navigate. Link to a source or related explanation when it adds value.
10.4.2Blogs and Social Posts
Use a voice that suits the audience and the space. A personal reflection can be conversational; a public announcement may need a more direct structure.
Choose a clear opening and keep the piece focused. Include a call to action only when there is something useful for the reader to do.
10.4.3Emails and Messages
Tell the reader why you are writing and give the details they need. Put a time, place, question, or requested action where it is easy to find.
Example: We’re meeting at the café on Saturday at ten. Can you join us?
Use a subject line for an email when it helps set expectations. Match the tone to the relationship, and reread the message for details the recipient would otherwise have to ask about.
Product and Release WritingOptional reference
10.5Writing About Products
If you’re writing about something you make, explain what it does and why someone might use it. Give practical details without making readers work through a sales pitch. Keep facts current when the thing changes.
10.5.1Changelogs and Release Notes
- Use consistent formatting to highlight version numbers, dates, and updates.
- Categorize entries (e.g., New Features, Fixes, Improvements).
- Be concise and transparent.
- Include impact and next steps when necessary.
10.5.2Product Overviews
Explain what the product is, who might find it useful, and how it fits into their day. Name a concrete benefit and give readers a way to learn more.
Let specific details carry the appeal. Words such as revolutionary add little when they replace an explanation.
10.5.3New Product and Feature Guides
- Provide instructions, use cases, and visuals.
- Highlight what’s new, how it works, and what to do next.
- Useful when readers need to understand a change and decide what to do next.