> ## Documentation Index
> Fetch the complete documentation index at: https://josephfajen.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Marlowe Documentation

> 17,900 lines of developer documentation for a smart contract platform — built from the ground up

## 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.io](https://docs.marlowe.iohk.io/docs/introduction)

***

## What I Delivered

<CardGroup cols={2}>
  <Card title="17,900+ Lines" icon="file-lines">
    Documentation written across 124 files. Full developer-facing content
    including tutorials, conceptual guides, API reference, and troubleshooting.
  </Card>

  <Card title="41-Tutorial Series" icon="graduation-cap">
    End-to-end tutorial series taking developers from first Marlowe contract to
    production deployment. Structured around 5 user personas.
  </Card>

  <Card title="93-Schema OpenAPI Spec" icon="code">
    Collaborated with engineers to integrate a 93-schema OpenAPI specification
    directly into the documentation site. Auto-generated reference from source.
  </Card>

  <Card title="5 User Personas" icon="users">
    Designed information architecture with visual pathway diagrams so each developer
    type could find their appropriate starting point.
  </Card>
</CardGroup>

***

## 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

**Result:** [Enhanced API Reference](https://joseph-fajen.github.io/marlowe-api-docs/)

> 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`