Writing & Documentation

I led documentation at StarkWare and write for Mastercard. The writing sits alongside delivery and engineering leadership. It is the reason my reviews get acted on and my decisions survive the people who made them leaving. This page holds the samples and the method.

Samples

Starknet

I was Documentation Lead for the open-source Starknet docs (opens in a new tab) from 2022 to 2023.

What it demonstrates: zero-knowledge proof systems and a new smart contract language explained for readers from ZK researchers to dApp developers.

Klevu

Installation guides, API testing and usage docs for the Klevu integrations, alongside the solutions architecture work, 2018 to 2020.

What it demonstrates: integration guides for Magento, BigCommerce and Shopify, written for merchants and developers who need different things from the same product.

Mastercard MDES

Enterprise structured authoring in DITA XML, under Mastercard brand standards and W3C COGA accessibility guidance. The output is not public. The scope and approach are on the MDES page.

Platform Audit Reports

Between 2018 and 2020 I wrote 60 to 165-page structured technical reports for clients, with a scored summary and a ranked recommendations table. They are client confidential. The format is on Consultancy, Audits & Klevu.

This Site

A working sample in itself. Nextra, custom information architecture and a documentation conceit carried across the whole site.

Method

Documentation is a product

It needs information architecture, a maintenance owner, a release process and a feedback loop. Treated as a chore at the end of a sprint, it rots inside a quarter.

Clarity before cleverness

The goal is a reader who can act. Precision matters and so does plain language, and where those two pull apart, I keep the precision and rewrite the sentence.

Write from the system, not about it

I read the code, run the product and test the procedure before documenting it. That is why the first draft is usually accurate, and why I find gaps the engineering team had stopped seeing.

Structure for retrieval

Self-contained topics, explicit headings, no meaning buried in the transition between paragraphs. This has always been good practice for a reader scanning a page. It is also what makes content usable by an AI assistant. I built the repository behind Mastercard's conversational-AI proof of concept this way. See AI Enablement.

Before and After

Typical reference entry:

"The transfer function moves tokens from one address to another. It takes two parameters: recipient (address) and amount (uint256)."

How I would write it:

Transferring tokens

Use transfer() to send tokens to another address:

token.transfer(recipient, amount);

Parameters:

• recipient: destination address (must be a valid Ethereum address)
• amount: number of tokens to transfer, in the smallest unit

Important: this reverts if your balance is insufficient. Check balanceOf() first when handling user input.

Common pitfalls:

• ❌ Forgetting to approve tokens for contracts
• ❌ Not handling transaction failures
• ✅ Validating addresses before transferring

The difference: context arrives before the code, the example runs, the failure case is named, and the reader knows what to do next.

Tooling

Structured authoring: DITA XML, DITA-OT, AsciiDoc Docs-as-code: Docusaurus, Nextra, GitBook, MkDocs, Markdown, MDX Quality: Vale, review workflows in Git Pipelines: GitHub Actions, GitLab CI

Request Something Specific

Need to see material for a particular domain, audience or format? → Get in touch and I will send something relevant or write a short custom example.