Technical Writing and Documentation 101: How‑To Guides and Procedures (Task‑oriented, Screenshots, GIFs)

How‑To Guides and Procedures (Task‑oriented, Screenshots, GIFs)

How-To Guides and Procedures: A Practical Study Guide for Technical Writers

What This Is

How-to guides and procedures are task-oriented documentation that walk users through specific actions to achieve a goal—like setting up a cloud server, integrating a payment API, or troubleshooting a software error. Unlike conceptual docs (which explain why something works) or reference docs (which list what exists), how-to guides focus on how to complete a task step-by-step.
Example: Stripe’s “Accept a Payment” guide shows developers exactly how to implement a checkout flow, with code snippets, screenshots, and error-handling tips.

Key Terms & Tools

• How-To Guide (Task Topic): A step-by-step document solving a specific user problem (e.g., “How to Deploy a Docker Container on AWS”). Structured as Goal → Prerequisites → Steps → Verification.
• Procedure: A formal, often numbered sequence of steps (e.g., “Reset Your Password” in a SaaS app). Common in compliance-heavy industries (healthcare, finance).
• Screenshots: Static images of UIs, annotated with callouts (e.g., arrows, boxes) to highlight key areas. Tools: Snagit, Greenshot, Figma (for annotations).
• GIFs/MP4s: Short, looping animations showing dynamic processes (e.g., “How to Navigate the Dashboard”). Tools: ScreenToGif, Kap, Loom (for voiceovers).
• Docs-as-Code: Treating docs like software—stored in Git, written in Markdown/AsciiDoc, built with static site generators (Sphinx, Docusaurus, MkDocs), and reviewed via pull requests.
• OpenAPI (Swagger): A YAML/JSON spec for REST APIs. Tools like Swagger UI or Redoc auto-generate interactive API docs from the spec.
• DITA (Darwin Information Typing Architecture): An XML-based standard for modular docs. Uses topics (concept/task/reference) and maps to assemble guides. Tools: Oxygen XML, DITA-OT.
• Static Site Generators (SSGs): Tools that convert Markdown/AsciiDoc into HTML websites. Examples: Hugo, Jekyll, VitePress.
• Markdown: A lightweight markup language for formatting text. Syntax quirks: bold, *italic*, `code`, [links](url).
• AsciiDoc: A more powerful alternative to Markdown, supporting tables, cross-references, and conditional content. Tools: Asciidoctor, Antora.
• Version Control (Git): Tracks changes to docs, enabling collaboration. Key commands: git add, git commit, git push, git branch.
• Continuous Integration/Deployment (CI/CD): Automates doc builds and deployments (e.g., GitHub Actions, Netlify, Vercel).

Step-by-Step / Process Flow

1. Define the Goal and Audience

• Action: Identify the exact user problem (e.g., “How to Set Up OAuth for a Slack App”).
• How:
• Interview SMEs (Subject Matter Experts) or developers to confirm the task’s scope.
• Check support tickets or forums for common pain points.
• Write a user story: “As a developer, I want to authenticate my Slack app so users can log in with their Slack accounts.”
• Example: Stripe’s OAuth guide starts with a clear goal: “Add a ‘Connect with Stripe’ button to your platform.”

2. Break the Task into Steps

• Action: Decompose the task into small, actionable steps (3–10 steps max).
• How:
• Use imperative verbs (e.g., “Click,” “Enter,” “Run”).
• Group related steps (e.g., “Step 1: Configure Your App” → “Step 2: Generate API Keys”).
• Add prerequisites (e.g., “You must have a Slack workspace admin account”).
• Example:

  Step 1: Create a Slack App
  1. Go to api.slack.com/apps.
  2. Click Create New App.
  3. Select From scratch and enter your app name.

  
  

3. Add Visuals (Screenshots, GIFs, Diagrams)

• Action: Illustrate complex or UI-heavy steps with visuals.
• How:
• Screenshots: Capture only the relevant UI (crop out distractions). Use Snagit or Greenshot for annotations.
  • Pro tip: Add numbered callouts (e.g., “1. Click the gear icon”) to match step numbers.
• GIFs: Record short (5–10 sec) loops for dynamic actions (e.g., “How to Drag-and-Drop a File”). Use ScreenToGif or Kap.
• Diagrams: Use Mermaid.js (for Markdown) or Lucidchart for flowcharts.
• Example:
  Source: Slack API Docs

4. Write for Clarity and Scannability

• Action: Optimize for readability and quick scanning.
• How:
• Use short sentences (15–20 words max).
• Bold key terms (e.g., “Enter your Client ID in the field.”).
• Add code blocks for commands/API calls (use syntax highlighting).
  bash
curl -X POST https://api.slack.com/api/oauth.v2.access \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"
• Include warnings/notes (e.g., “⚠️ This will revoke all existing tokens.”).
• Example: GitHub’s “Creating a Personal Access Token” guide uses collapsible sections for optional steps.

5. Test the Procedure

• Action: Follow your own guide to verify accuracy.
• How:
• Step-by-step testing: Perform each step as written. Note where you get stuck.
• Fresh environment: Test on a new machine or incognito browser to catch missing prerequisites.
• Peer review: Have a non-expert (e.g., a junior dev) try the guide. Fix unclear steps.
• Example: If a step says “Run npm install”, test it in a fresh directory to ensure dependencies are listed.

6. Publish and Maintain

• Action: Deploy the guide and set up maintenance processes.
• How:
• Docs-as-Code: Store the guide in Git (e.g., GitHub/GitLab). Use pull requests for updates.
• CI/CD: Automate builds with GitHub Actions or Netlify.
• Feedback loops: Add a “Was this helpful?” button or link to a Slack channel for questions.
• Versioning: Use semantic versioning (e.g., v1.2) for major updates. Tag docs with the software version they apply to.
• Example: Twilio’s “Send an SMS” guide includes a “Need help?” link to support.

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Task decomposition: Can you break a complex process into clear, logical steps? Example: Instead of “Set up the database”, write:

   
   

   1. Install PostgreSQL.
   2. Run createdb myapp.
   3. Update config/database.yml with your credentials.

2. Visual storytelling: Do you use screenshots/GIFs effectively? Show a before/after (e.g., a messy UI vs. a clean, annotated screenshot).

3. Docs-as-Code proficiency: Can you write in Markdown/AsciiDoc, use Git, and set up a static site generator? Include a GitHub repo with your docs in your portfolio.

4. Distinguishing guide types:

5. Tutorial (teaches concepts by building, e.g., “Build a To-Do App with React”) vs.
6. How-To Guide (solves a specific problem, e.g., “Add Dark Mode to Your React App”).
7. Reference (lists facts, e.g., “React Hooks API”) vs.
8. Explanation (explains why, e.g., “How React’s Virtual DOM Works”).

Portfolio Tips

• Include a “How-To” guide in your portfolio (e.g., “How to Deploy a Flask App on Heroku”).
• Show your process: Add a README explaining how you researched, tested, and iterated on the guide.
• Compare tools: Write a short blog post on “Swagger UI vs. Redoc: Which Should You Use for API Docs?”

Quick Check Questions

1. A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?

Answer: Implement docs-as-code with CI/CD (e.g., auto-generate docs from OpenAPI specs on every git push). Use GitHub Actions to run swagger-cli validate and fail builds if the spec is invalid.
Why: Manual updates are error-prone; automation ensures docs match the code.

2. A user says your “How to Reset Your Password” guide is too vague. What’s the most likely issue, and how would you fix it?

Answer: The guide probably skips steps (e.g., “Go to Settings” without saying how) or assumes prior knowledge (e.g., “Enter your recovery email” without defining it). Fix by: - Adding screenshots of each step.
- Including prerequisites (e.g., “You must have access to the email linked to your account”).
Why: Users abandon guides if they can’t follow along.

3. You’re writing a guide for a CLI tool. Should you use screenshots or code blocks?

Answer: Code blocks (with syntax highlighting) for commands/output, and screenshots only for complex terminal UIs (e.g., htop). Example:

# Install the tool
npm install -g my-cli-tool

# Run a command
my-cli-tool deploy --env production

Why: Screenshots of terminals are hard to read and can’t be copied/pasted.

Last-Minute Cram Sheet

1. How-To Guide Structure: Goal → Prerequisites → Steps → Verification → Troubleshooting.
2. Imperative voice: “Click the button” (not “The button should be clicked”).
3. Screenshots: Crop to only the relevant UI, add numbered callouts.
4. GIFs: Keep under 10 seconds, use ScreenToGif or Kap.
5. Markdown syntax:
6. Bold: text
7. Code: `code`
8. Link: [text](url)
9. OpenAPI vs. Swagger UI:
10. OpenAPI = spec (YAML/JSON).
11. Swagger UI = interactive docs generated from the spec.
12. Docs-as-Code: Store docs in Git, write in Markdown/AsciiDoc, build with Sphinx/Docusaurus.
13. ⚠️ Tutorial ≠ How-To Guide: A tutorial teaches concepts by building; a how-to solves a specific problem.
14. CI/CD for docs: Use GitHub Actions to auto-deploy docs on git push.
15. Versioning: Tag docs with the software version they apply to (e.g., “v2.1”).