What good documentation actually does

Documentation is a product surface.
Treat it like one.

Three things that are true about my work and can be verified right now. Not estimates. Not projections. Facts.

Publicly accessible portfolio pieces

Every piece is version-controlled, live, and readable right now. Not a PDF. Not a screenshot. Documentation you can evaluate the same way a developer would encounter it.

All six available at douglasebhoman.com/work

Published essays on documentation systems

Systems Over Sentences is a ten-part series on why documentation fails structurally and what to build instead. Every essay is public, dated, and open for comment.

Freelance since November 2025 · API docs · Docs-as-Code

Working days to audit delivery

You send me the link. I send you the report. A written diagnosis, prioritised action plan, and 30-minute walkthrough. Fixed fee. No scope creep.

€300 direct · Currently available

About the Writer

Most documentation is written for the person who built the product.
Not the person who has to use it.

That distinction sounds small. It is not. When an engineer documents a feature, they document what it does. What they forget, because they cannot unknow it, is that the reader arrives without that context. The reader does not need a description of the feature. They need a map from their problem to the solution.

I came to technical writing through creative writing. That is not a detour. Fiction trained me to analyse an audience's mental state before writing a single word, to understand what they are carrying, what they already know, and where they are likely to get lost. That is not a writing skill. It is an information architecture skill. And it is exactly what most technical documentation is missing.

I have worked as a freelance technical writer since November 2025, after completing a Diploma in Web Development in 2025. Everything I claim on this page links to work you can read.

“The reader does not need a description of the feature. They need a map from their problem to the solution.”

What drives me is not passion. It is responsibility: to be the advocate for the users who are quietly suffering the consequences of documentation nobody designed with them in mind.

I write fiction in Prague in the evenings, the same discipline as documentation, at its core: imagine the reader you have never met, understand what they need to know, and build something they can move through without getting lost.

Narrative is infrastructure. I treat it that way.

01 — Principle

Empathy before architecture

Knowing the reader’s pain point is not a soft skill. It is the baseline every documentation decision should be built on.

02 — Principle

Structure is a reader service

Findability is an architecture problem, not a writing problem. Good structure means the reader never has to guess what comes next.

03 — Principle

Narrative is infrastructure

Documentation written with narrative logic gets read. Documentation written without it gets skimmed, misunderstood, and ignored.

Documentation health check

Is your documentation
holding up as your product grows?

Six questions. Two minutes. A specific diagnosis of where your documentation system is failing and what it is costing you right now.

Selected work

Documentation built the way
engineers ship code.

View all work →

MkDocsGitHub PagesDocs-as-Code

MkDocs for Technical Writers

The problem

Writers adopting Docs-as-Code had no guide that didn’t require a developer alongside them.

What I built

A complete guide from installation through production deployment, written for writers not engineers.

Result: Removes the developer dependency from the onboarding process entirely.

Read the documentation→

API DocsRESTPostman

OpenWeather API — Getting Started Guide

The problem

Engineers had no clear path from authentication to a working first API call.

What I built

End-to-end docs covering auth, endpoints, parameters, and response interpretation.

Result: Eliminates the most common first-session failure points for new API users.

Read the documentation→

GitHub PagesDNSCloudflare

Personal Website Setup Guide

The problem

GitHub Pages, DNS, HTTPS, and email setup had no single coherent reference.

What I built

End-to-end docs covering every component, with troubleshooting for every common failure point.

Result: Collapses a multi-day setup process into a single navigable document.

Read the documentation→

ArchitectureCI/CDInternal Docs

douglasebhoman.com — Site Documentation

The problem

Portfolio sites are typically undocumented black boxes, hard to maintain, impossible to hand off.

What I built

Internal-style docs: architecture, local setup, deployment pipeline, contributing guidelines.

Result: A site that documents itself, the same standard I apply to every client engagement.

Read the documentation→

Documentation in practice

Not screenshots. Not PDFs.
Actual documentation, rendered live.

The best way to evaluate a technical writer is to read their work in context. Each tab below shows a real excerpt from a real piece, structured, styled, and readable exactly as a developer would encounter it. This is the creative-technical blend in practice.

openweathermap-api.md

GET/data/2.5/weather?q={city}&appid={API_key}

Current Weather Data

Returns the current weather for a given location. Supports lookup by city name, city ID, geographic coordinates, or ZIP code. Responses are in JSON by default.

Before you begin New API keys activate within 10 minutes of generation. If you receive a 401 Invalid API key error immediately after creating a key, wait 10 minutes and try again.

Request parameters

Parameter	Type	Required	Description
`q`	string	Yes*	City name. Add country code for precision: `London,uk`
`appid`	string	Yes	Your API key
`units`	string	No	`metric` (°C), `imperial` (°F). Default: Kelvin

Example request

curl "https://api.openweathermap.org/data/2.5/weather?q=London,uk&units=metric&appid=YOUR_API_KEY"

Response

{"weather":[{"main":"Clouds","description":"overcast clouds"}],"main":{"temp":15.2,"feels_like":14.1,"humidity":82},"wind":{"speed":5.1,"deg":200},"name":"London"}

getting-started.md

Getting Started with MkDocs

MkDocs is a static site generator for building project documentation from Markdown files. This guide takes you from installation to a live documentation site, no prior experience required.

Prerequisites Python 3.8 or later. Run python --version to check.

Installation

Install MkDocs

pip install --upgrade mkdocs

Create a new project

mkdocs new my-project && cd my-project

Start the development server

mkdocs serve

architecture.md

Site Architecture

This document describes the technical architecture of douglasebhoman.com. Written for future maintainers who need to understand how the site is structured without reverse-engineering it from source.

Technology stack

Layer	Technology	Why
Generator	Eleventy 3	One shared post layout and one posts collection build every page.
Scripts	Vanilla JavaScript	No front-end framework.
Styles	Custom CSS	Zero dependencies. Full design control.
Hosting	GitHub Pages	Deployed by a GitHub Actions workflow on every push to main.
DNS	Cloudflare	DNS only, proxy off. HTTPS is issued by GitHub Pages.
Docs	MkDocs + Material	Separate repository, built and deployed by GitHub Actions.

Deployment Every push to main runs a GitHub Actions workflow that builds the site with Eleventy and publishes the output to GitHub Pages.

git-for-writers.md

Git for Technical Writers

Git is version control software originally built for code. As a technical writer, you will use it to track changes to documentation, collaborate with engineers, and publish updates without emailing files.

Why Git matters for writers When your documentation lives in Git alongside the code it describes, documentation debt becomes a code review problem, not a backlog problem.

The four commands you will use 90% of the time

git pull origin main
git checkout -b docs/update-api-authentication
git add docs/authentication.md
git commit -m "docs: clarify token expiry behaviour in auth guide"

The service

Start with the
Documentation Audit.

Most teams know their documentation is a problem. They don’t know exactly where it’s failing or what to fix first. That’s what the audit solves. I read everything. I identify the structural failures and rank them by impact. You get a written report and a 30-minute call. No vague feedback. No generic advice. A clear, prioritised plan you can act on immediately.

Full documentation review

Every page assessed across accuracy, structure, ownership, and findability. Nothing assumed, nothing skipped.

Prioritised action plan

Every finding ranked by impact. You know exactly what to fix first, and why.

Structural recommendations

Not just what’s broken: what to build instead. Architecture, ownership model, and system logic.

30-minute walkthrough call

I walk you through every finding. You can ask questions, push back, and leave knowing exactly what happens next.

Delivered in 5 working days

You send me the link. I send you the report. Fixed timeline, fixed fee. No scope creep, no surprises.

Limited availability. Currently taking new audit clients.

See all services →

Documentation Audit
I read your docs. You get clarity.

Fixed fee · No surprises · 5 working days

€300

One fixed fee. Everything included.

Delivered in 5 working days

This is the direct booking price. The audit is also offered on Upwork as three packages, from $150 to $650, each with its own scope and priced in US dollars.

Consider this

One unclear endpoint does not cost you once. It costs you every time a developer reaches it, gets stuck, and opens a support ticket. The audit tells you which pages are doing that.

Book the Documentation Audit →

Send a message first

Prefer to hire through Upwork? See the audit packages →

How it works

From first contact to delivered system.

Audit

I review your documentation against four dimensions: accuracy, structure, ownership, and findability. You receive a written report and a 30-minute walkthrough within five working days.

You find out exactly what is broken.

Diagnose

We identify structural problems and prioritise what to fix first, and why. Every recommendation is ranked by impact, not by how easy it is to implement.

You know where to start.

Build

I design and implement the documentation system: architecture, templates, ownership model, deployment pipeline. The kind that stays accurate as your product grows.

You get a system, not a document.

Hand off

Your team owns everything. I document the system itself so you can maintain it without me. The goal is independence, not dependency.

You don’t need me forever.

docs-strategy.md

1# Documentation Strategy

3## Core principles

4- Empathy before architecture

5- Structure is a reader service

6- Narrative is infrastructure

8## Audit dimensions

9- [x] Accuracy

10- [x] Structure

11- [x] Ownership

12- [x] Findability

Recommendation

In a reader’s own words.

Quoted with permission

“A must-read if you want to adopt Git and GitHub for product documentation.”

Douglas has nailed it with his Git and GitHub for Technical Writers series. He has a knack for writing in a simple, clear style. It is a pleasure to read.

Tejas Dandekar

Associate Director, DP&S

Tejas wrote this about my six-part Git and GitHub for Technical Writers series, in an email he has allowed me to quote.

What the audit looks for

Documentation problems usually present as writing problems: pages out of date, users who cannot find what they need, one engineer who is the only source of truth. Underneath, the cause is often structural. Nobody owns the page, nothing triggers an update, and there is no path from the reader’s problem to the answer.

The audit is built to make that structure visible, then rank what to fix by impact.

€300

direct booking · five working days · fixed scope

Book the audit →

All six portfolio pieces publicly accessible on GitHub

✦ Document360 content partner · documentation published and live

Get started

The audit is where you find out
exactly what is broken.

Every sprint that ships without a documentation update widens the gap. Your users are paying for it: in confusion, in support tickets, in churn nobody is measuring. The audit gives you a prioritised action plan in five working days. Specific findings. No generic advice.

Limited availability. Currently taking new audit clients.

Worth considering

One unclear endpoint does not cost you once. It costs you every time a developer reaches it, gets stuck, and opens a support ticket. The audit is a fixed fee, so you know the cost before you start.

Documentation Audit — I read your docs. You get clarity.

A full review across accuracy, structure, ownership, and findability. Every finding is specific. Every recommendation is actionable.

Full review across all four dimensions
Prioritised action plan with specific next steps
Structural recommendations and ownership map
30-minute walkthrough call
Written report in five working days

€300

Fixed fee · No surprises

Delivered in 5 working days

This is the direct booking price. The audit is also offered on Upwork as three packages, from $150 to $650, each with its own scope and priced in US dollars.

Book the Documentation Audit → Send a message Prefer to hire through Upwork? See the audit packages →

Read the blog → All services →

Your product is scaling.Your documentation isn’t.

Is your documentationholding up as your product grows?

Documentation built the wayengineers ship code.

Not screenshots. Not PDFs.Actual documentation, rendered live.

Current Weather Data

Request parameters

Example request

Response

Getting Started with MkDocs

Installation

Site Architecture

Technology stack

Git for Technical Writers

The four commands you will use 90% of the time

Start with theDocumentation Audit.

From first contact to delivered system.

In a reader’s own words.

The audit is where you find outexactly what is broken.

Your product is scaling.
Your documentation isn’t.

Is your documentation
holding up as your product grows?

Documentation built the way
engineers ship code.

Not screenshots. Not PDFs.
Actual documentation, rendered live.

Start with the
Documentation Audit.

The audit is where you find out
exactly what is broken.