How I work

My process, written as a runbook. It flexes for the project, but these steps rarely get skipped.

1. Start with the reader, not the feature

Before I write a word, I answer three questions:

• Who is reading? A developer at a partner bank, an admin in a portal, an ops analyst in the middle of a dispute?
• What are they trying to do? Not “learn about the feature”, but “get a payout to settle” or “close this dispute within the SLA”.
• What do they already know? This decides what I explain and what I link.

Different readers get different doc types. A developer gets a reference and a quickstart. An ops analyst gets an SOP with decision points. A partner executive gets a two-paragraph email that Legal has already approved.

2. Stay ahead of the release calendar

At Kissflow, I supported four product managers on different products at the same time. At PayPal, it’s eight, spread across San Jose, Chicago, Singapore and India. With that many owners, the real risk isn’t bad writing. It’s hearing about a release too late, or losing the week to meetings. So I run a lightweight intake rhythm.

One short sync at the start of every week. At Kissflow, that was a single call with all four PMs. At PayPal, it’s short, focused calls with each PM, scheduled around their time zones. Every call covers the same four questions:

Plan the week from the answers. Every document is fully reviewed and published right before or alongside its release, never after it.

Respect everyone’s time, including mine. I keep my questions short and specific so PMs spend minutes with me, not hours. I also skip meetings where I’m not needed and catch up from the notes, which keeps my days for writing.

3. Learn the domain properly

I don’t document what I don’t understand. For a new domain I read the specs, map the flows myself, and then go to engineers with specific questions:

4. Test it myself

If there’s an API, I call it. I use Postman to run every endpoint I document so the examples are real responses, not guesses. If the docs say a field is optional, I’ve tried leaving it out.

5. Draft in the open

I write in Markdown in VS Code or Cursor, in Git, the same way engineers work. Drafts go up as pull requests so engineers and QA can review changes line by line, next to the code they describe.

When a project needs one source to publish to several products, audiences or formats, I use structured authoring instead: typed DITA topics in Oxygen XML, with content reuse and conditional filtering. See a DITA sample →

6. Review for accuracy, then for clarity

Two passes, in this order:

1. Accuracy: engineering and QA confirm it’s true, and Legal and Compliance confirm it’s allowed.
2. Clarity: I edit against the style guide, usually a house guide built on Google’s or Microsoft’s. Shorter sentences, active voice, one idea per paragraph, and consistent terms.

7. Publish and keep it alive

Docs are never finished. I track portal bugs and doc issues in Jira alongside engineering work, update docs as part of each release, and treat outdated docs as bugs.

8. Make quality scale beyond me

When I’m the only writer, I build systems so other people’s docs are good too:

• A style guide people actually follow, because it’s short and has examples
• Templates and Cursor rules that make the right structure the easy one
• Review checklists engineers can run without me

Principles I keep coming back to

• Clear beats clever. (Except on this website.)
• Every example should run. A broken code sample costs more trust than a missing one.
• Consistency is a feature. If it’s a “participant” on page one, it’s not a “partner” on page two.
• The best doc is sometimes a better error message. I’ll push for a fix in the product before writing a workaround.

© 2026 Akaash Amalraj · Built with Astro, written by a human, reviewed by a style guide. · llms.txt