Technical Writing
Random

Click random to get a fresh chapter.

Technical Writing and Documentation 101: Plain Language and Readability (Flesch?Kincaid, Active Voice, Global English)

Plain Language and Readability (Flesch?Kincaid, Active Voice, Global English)

Plain Language & Readability in Technical Writing: A Portfolio-Ready Study Guide

What This Is

Plain language and readability ensure that documentation is clear, concise, and usable—whether it’s an API reference for a payment gateway (e.g., Stripe’s /charges endpoint) or a getting-started guide for a cloud service (e.g., AWS Lambda setup). Poor readability frustrates users, increases support tickets, and slows adoption. For example, compare: - Before (passive, jargon-heavy): "The configuration of the payment processor is to be performed by the user prior to the initiation of a transaction." - After (active, plain language): "Set up your payment processor before processing transactions."

This guide covers Flesch-Kincaid readability scores, active voice, and Global English—tools and techniques to make docs faster to read, easier to translate, and more inclusive for global audiences.

---

Key Terms & Tools

• Plain Language: Writing that’s clear, concise, and free of unnecessary jargon. Goal: Users can find, understand, and act on information the first time. Example: Replace "utilize" with "use" and "in the event that" with "if."

• Flesch-Kincaid Readability Tests:

• Flesch Reading Ease: Scores text from 0 (hard) to 100 (easy). Aim for 60–70 for technical docs (high school level).

• Flesch-Kincaid Grade Level: Estimates U.S. school grade needed to understand the text. Target 7th–9th grade for developer docs. Tools: Hemingway Editor, Microsoft Word’s built-in checker, Readable.com.

• Active Voice: The subject performs the action (e.g., "The API returns a response" vs. "A response is returned by the API"). Why? Active voice is shorter, clearer, and more direct.

• Global English: Simplified English for non-native speakers. Avoid:

• Idioms ("hit the ground running")
• Cultural references ("like a bull in a china shop")

• Complex metaphors Example: Replace "This feature is a game-changer" with "This feature improves performance."

• Style Guides:

• Microsoft Writing Style Guide (free, modern, tech-focused)
• Google Developer Documentation Style Guide (APIs, Markdown, tone)

• IBM’s Simplified Technical English (aerospace/defense, but useful for global audiences)

• Docs-as-Code Tools for Readability:

• Markdown: Lightweight syntax for plain-text docs (e.g., GitHub, GitLab, VS Code).
• AsciiDoc: More powerful than Markdown (tables, cross-references, conditional content).

• Static Site Generators (SSGs): Hugo, Docusaurus, or Sphinx (auto-check readability with plugins).

• OpenAPI/Swagger: API specs that can auto-generate docs. Use plain language in descriptions (e.g., "This endpoint creates a new user" vs. "POST /users"). Tools: Swagger UI, ReDoc, Stoplight.

• Linters for Readability:

• Vale: Checks for passive voice, jargon, and style guide compliance (works with Markdown, AsciiDoc).

• Alex: Catches insensitive/biased language (e.g., "whitelist"-"allowlist"). Example Vale rule: yaml # .vale.ini [*.md] BasedOnStyles = Microsoft, Google

• Accessibility & Readability:

• WCAG (Web Content Accessibility Guidelines): Ensure docs work for screen readers (e.g., alt text for images, semantic HTML).
• Contrast ratios: Text should have at least 4.5:1 contrast (use WebAIM Contrast Checker).

---

Step-by-Step: Writing for Readability

1. Plan for Your Audience

• Action: Identify the user’s goal and skill level.
• Example: A beginner tutorial for AWS Lambda might explain "serverless" in simple terms, while an API reference assumes the user knows HTTP methods.
• Tool: Create a persona doc (e.g., "DevOps engineer, intermediate Python, needs to deploy a function in <10 mins").

2. Draft in Plain Language

• Action: Write a first draft, then edit for clarity.
• Before: "The aforementioned configuration parameters must be populated prior to the execution of the script."
• After: "Set these parameters before running the script."
• Tool: Use Hemingway Editor to highlight passive voice, complex sentences, and adverbs.

3. Test Readability Scores

• Action: Run your draft through a readability checker.
• Example: In Microsoft Word: Review-Spelling & Grammar-Readability Statistics-Flesch-Kincaid Grade Level
• Goal: Grade 7–9 for developer docs, Grade 5–7 for end-user guides.
• Tool: Readable.com (paid) or Grammarly (free tier).

4. Simplify for Global English

• Action: Replace idioms, metaphors, and cultural references.
• Before: "This feature is a piece of cake."
• After: "This feature is easy to use."
• Tool: Alex.js (linter for insensitive language) or IBM’s Simplified Technical English checker.

5. Add Visuals & Examples

• Action: Break up walls of text with:
• Code samples (e.g., curl, Python, JavaScript)
• Screenshots (annotated with arrows/callouts)
• Tables (for parameters, error codes)
• Example: markdown | Parameter | Type | Required | Description | |-----------|--------|----------|---------------------------| | `amount` | number | Yes | Payment amount in cents. |

6. Peer Review & Iterate

• Action: Submit a pull request (PR) for developer review.
• Why? Engineers catch technical inaccuracies; writers catch clarity issues.
• Tool: GitHub/GitLab PRs with Vale linter for style checks.
• Action: User-test with a non-technical colleague (e.g., "Can you follow these steps without asking me questions?").

---

Common Mistakes

Mistake	Correction	Why?
Overusing passive voice	Rewrite in active voice: "The system processes the request"-"The API processes your request."	Active voice is 20–30% easier to read (Nielsen Norman Group).
Assuming prior knowledge	Define acronyms on first use (e.g., "REST (Representational State Transfer)").	30% of users abandon docs if they don’t understand the first paragraph.
Writing long paragraphs	Break into bullet points, short sentences, or subheadings.	Users scan docs; 79% of users skim (NN/g).
Using jargon without explanation	Replace "idempotent" with "The API won’t create duplicate records if you retry."	Global English ensures non-native speakers understand.
Ignoring accessibility	Add alt text for images, use semantic HTML, and check color contrast.	1 in 4 adults in the U.S. has a disability (CDC).

---

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Portfolio Samples:
2. Include before/after edits (e.g., a jargon-heavy API doc you rewrote in plain language).
3. Show readability metrics (e.g., "Improved Flesch-Kincaid score from 45 to 70").

4. Example: A GitHub repo with:

   • Original doc (e.g., api-reference-original.md)
   • Revised doc (e.g., api-reference-plain-language.md)
   • A README explaining your changes.

5. Tricky Distinctions:

6. Conceptual Doc vs. Tutorial:
   • Conceptual: Explains what (e.g., "How OAuth 2.0 Works").
   • Tutorial: Teaches how by building (e.g., "Build a Login System with OAuth").
7. Reference vs. Guide:
   • Reference: Facts only (e.g., API endpoint parameters).
   • Guide: Step-by-step (e.g., "How to Process Payments with Stripe").

8. Swagger UI vs. ReDoc:

   • Swagger UI: Interactive, good for testing APIs.
   • ReDoc: Cleaner, better for static docs.

9. Behavioral Questions:

10. "How would you handle a developer who says your docs are too verbose?"

    • Answer: "I’d ask for specific examples, then rewrite those sections in plain language and test readability scores. I’d also add a TL;DR at the top for quick reference."

11. Take-Home Tests:

12. Expect tasks like:
    • "Rewrite this API doc for a non-technical audience."
    • "Improve the readability of this CLI guide (Flesch-Kincaid score: 30)."
13. Tip: Use Hemingway Editor and Vale to polish your submission.

---

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 automated checks: - Store docs in Git alongside code. - Use OpenAPI/Swagger to auto-generate API docs from code annotations. - Add CI/CD checks (e.g., GitHub Actions) to flag mismatches between code and docs. Why? 60% of API docs are outdated (SmartBear 2023). Automation reduces drift.

2. Your manager asks you to write a tutorial for beginners. How do you structure it for readability?

Answer: Use the "Task-Based" format:
1. Goal: "By the end, you’ll have a working Python script that fetches weather data."
2. Prerequisites: "You’ll need Python 3.8+ and a free API key."
3. Step-by-Step: Short paragraphs, code blocks, and screenshots.
4. Troubleshooting: Common errors (e.g., "If you get a 403 error, check your API key.") Why? Beginners need clear goals, minimal prerequisites, and error handling.

3. A non-native English speaker struggles with your docs. How do you adapt?

Answer: Apply Global English principles: - Replace idioms ("bite the bullet"-"proceed despite difficulty"). - Use simple verbs ("terminate"-"end"). - Add visuals (diagrams, tables) to reduce text. - Test with Google Translate to catch ambiguous phrasing. Why? 75% of internet users are non-native English speakers (W3Techs).

---

Last-Minute Cram Sheet

1. Flesch-Kincaid Grade Level: Aim for 7th–9th grade for developer docs.
2. Active Voice: "The API returns a response" > "A response is returned by the API."
3. Global English: Avoid idioms, metaphors, and cultural references.
4. Hemingway Editor: Highlights passive voice, complex sentences, and adverbs.
5. Vale Linter: Checks for style guide compliance (e.g., Microsoft, Google).
6. Markdown Tip: Use backticks for code and bold for UI elements.
7. OpenAPI: Use plain language in description fields (e.g., "Creates a new user").
8. Accessibility: Alt text for images, 4.5:1 contrast ratio, semantic HTML.
9. Tutorial-How-To: A tutorial teaches concepts by building; a how-to solves a specific problem.
10. Docs-as-Code: Store docs in Git, review via PRs, auto-check with CI/CD.