Before-After Documentation Transformations — Show Your Improvement Process

In this tutorial, you will learn about Before. We cover key concepts, practical examples, and best practices to help you master this topic.

A before-after documentation transformation is a side-by-side comparison of original and improved documentation that demonstrates your ability to identify clarity issues, restructure content, and apply technical writing best practices.

In this tutorial, you will learn how to find documentation that needs improvement, analyze its weaknesses, rewrite it effectively, and present the transformation in a way that highlights your editing and writing skills.

What You'll Learn

You will understand how to select documentation for improvement, analyze common clarity problems, apply rewriting techniques, and present before-after comparisons that demonstrate your value as a technical writer.

Why It Matters

Before-after transformations are one of the most convincing portfolio pieces. They prove you can look at existing documentation, identify what is wrong, and fix it. This skill is exactly what hiring managers at DodaTech look for when evaluating writers for documentation improvement projects.

Real-World Use

The DodaZIP documentation Repository had 47 documentation issues reported by users. A technical writer created before-after examples for 5 of the most confusing pages, presented them in her portfolio, and was hired to rewrite the entire documentation set based on those samples.

flowchart LR
  A[Find Documentation] --> B[Analyze Weaknesses]
  B --> C[Identify Audience]
  C --> D[Plan Improvements]
  D --> E[Write Improved Version]
  E --> F[Create Side-by-Side]
  F --> G[Annotate Changes]
  G --> H[Add Explanation]
  H --> I[Publish to Portfolio]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Teacher Mindset

You might think only bad documentation needs rewriting. The truth is every documentation set can improve. Even well-written pages can benefit from better structure, clearer examples, or updated screenshots. The goal is not to prove the original author failed but to demonstrate your ability to make good documentation better.

Code Example: Before Version

### Configuration

To configure the app you need to edit the config file. The config file is called
config.yaml and it is in the root directory. You can change settings there. Some
important settings are the database URL and the API key. Make sure you set them
correctly or the app will not work. Also you can change the log level. The default
log level is INFO. You can set it to DEBUG for more information.

Code Example: After Version

### Configuration

The application is configured through `config.yaml` in the project root directory.

#### Required Settings

```yaml
database_url: "postgres://user:pass@localhost:5432/mydb"
api_key: "sk-abc123def456"

These settings are required. The application will not start without them.

Optional Settings

log_level: "INFO"  # Options: DEBUG, INFO, WARNING, ERROR

Set log_level to DEBUG during development for detailed logs. Change it to WARNING in production to reduce log volume.

## Code Example: Change Annotation Template

```markdown
## Changes Made

| Issue | Before | After | Reason |
|-------|--------|-------|--------|
| Paragraph walls | Single dense paragraph | Bullet lists and sections | Improves scannability |
| Missing code format | Settings described in text | YAML code blocks | Shows exact syntax |
| Unclear requirements | "must set them correctly" | Explicit required vs optional | Reduces configuration errors |
| No examples | No default values | Defaults shown in comments | Helps users understand options |

Common Mistakes in Before-After Transformations

1. Choosing Trivial Changes

Fixing a typo or grammar error does not demonstrate documentation skill. Choose examples that show structural improvements, better information architecture, or clearer explanations.

2. No Explanation of Changes

A side-by-side comparison without annotations forces the reader to guess what changed. Add callouts, annotations, or a change log that explains each improvement and why it matters.

3. Being Too Critical of the Original

Your goal is to demonstrate your skills, not to insult the original author. Frame the before version neutrally as documentation that could benefit from improvement, not as terrible writing.

4. Showing Only Aesthetic Changes

Changing font size or adding colors is not documentation improvement. Focus on clarity, structure, audience appropriateness, and completeness of information.

5. No Measurable Justification

Explain why your version is better. Reference principles like scannability, task completion, or reduced cognitive load. Connect each change to a specific user benefit.

Practice Questions

1. What makes a good candidate for a before-after transformation? Documentation with structural issues like paragraph walls, missing code examples, unclear navigation, inconsistent terminology, or missing audience focus. Avoid documentation that needs only minor copyediting.

2. How should you present a before-after comparison? Use a side-by-side layout or a table with the original and improved versions. Add annotations that highlight specific changes. Include a change log that explains each modification and its rationale.

3. What should you include in the explanation of your changes? The specific issue in the original, the change you made, the writing principle behind the change, and the expected benefit to the reader. Connect each change to a user outcome.

4. How many before-after examples should you include in your portfolio? Two to three examples showing different documentation types or different types of improvements. One tutorial rewrite, one API reference improvement, and one README enhancement provides good range.

5. Challenge: Find a documentation page that needs improvement. Create a before-after transformation with at least 5 specific changes. Present it in a table with annotations explaining each change and include a brief narrative about the improvement Strategy.

FAQ

Mini Project

Create a before-after documentation transformation. Find a documentation page in an open source project, analyze its weaknesses, rewrite it with at least 5 specific improvements, create a side-by-side comparison with annotations, add a change log explaining each modification, and publish it to your portfolio.

What's Next

Open Source Contributions in the next lesson. Then Blog Posts as Portfolio Pieces.