The Project
Input Output Global (IOG) — the blockchain research and engineering company behind the Cardano protocol — needed developer documentation for Marlowe, their smart contract platform tailored for financial applications. When I joined the team, the documentation was scattered and fragmented across repos and doc sites authored by various contributors at different stages of development. Collaborating with engineering, I rebuilt it from the ground up: conducted a comprehensive inventory, designed the information architecture, wrote and curated 17,900+ lines of content, and established a new docs site as the canonical source. I created 78% of repository commits over 13 months. Live documentation: docs.marlowe.iohk.ioWhat I Delivered
17,900+ Lines
Documentation written across 124 files. Full developer-facing content
including tutorials, conceptual guides, API reference, and troubleshooting.
41-Tutorial Series
End-to-end tutorial series taking developers from first Marlowe contract to
production deployment. Structured around 5 user personas.
93-Schema OpenAPI Spec
Collaborated with engineers to integrate a 93-schema OpenAPI specification
directly into the documentation site. Auto-generated reference from source.
5 User Personas
Designed information architecture with visual pathway diagrams so each developer
type could find their appropriate starting point.
The Scope in Numbers
| Metric | Value |
|---|---|
| Lines of documentation | 17,900+ |
| Files | 124 |
| Merged PRs | 59 |
| Repository commit share | 78% |
| OpenAPI schemas integrated | 93 |
| Tutorial count | 41 |
| User personas documented | 5 |
| Duration | 13 months |
Information Architecture
Marlowe attracts developers from different backgrounds — Haskell devs, Solidity devs, non-technical contract designers, infrastructure operators. One entry point doesn’t work for all of them. I designed an IA with 5 user personas and visual pathway diagrams so each type of developer could find their appropriate starting point without wading through content irrelevant to their use case.Enhanced OpenAPI Reference
After the Marlowe project concluded, I returned to the OpenAPI specification to enhance it for better developer experience. The original spec was functional but minimal. I added:- Semantic operation tags, grouping endpoints by workflow (contract creation, transaction submission, queries)
- Response documentation with structured descriptions for all response types
- Workflow guidance in endpoint descriptions — each operation tells developers what to call next
This work demonstrates my approach to API documentation: specs should teach workflows, not just list endpoints. Developers need to understand how pieces fit together.
Tech Stack
Markdown · MDX · Docusaurus · OpenAPI/Swagger · Git/GitHub · GitHub Actions