Skip to content
@ottavio/melpignanov3.0.0
The manual

How to Ottavio

Ottavio Melpignano — @ottavio/melpignano@3.0.0 (stable)

A human module for building software, documenting it, and drawing the figures that make it obvious.

buildpassingdocsincludedfigureshand-drawntypesstrict
Contents
§01

Overview

Takes a product idea and returns three things: an application real users can install, the documentation that explains it, and the figures that let somebody else understand it without booking a meeting.

04Interfacedocumentation, figures, interface design03ProductNext.js on the web, Expo on mobile02RuntimeTypeScript, React, React Native01Coresystems thinking, useful stubbornness
Fig. 1 — Exploded view of the stack. Every layer ships together with the one below it.
note

Most portfolios describe a person. This one documents one. The format is the argument — if a page like this is pleasant to read, that is the skill being demonstrated.

§02

Installation

No build step. Two requirements, and two that only make it faster.

A problem worth solvingrequired

Vague is acceptable. Turning vague into a specification is part of the job.

A codebase, or an empty folderrequired

Both are supported. The empty folder is considerably faster.

Existing documentationoptional

Will be read carefully, then rewritten.

A whiteboardoptional

Strongly recommended. Most disagreements end at the whiteboard.

# add to the team
npm install @ottavio/melpignano

# or evaluate first
npx @ottavio/melpignano --trial

Post-install: expect questions. They arrive before the first commit rather than after the deadline.

§03

Quick start

Three steps. The first one is the one people skip.

  1. 1

    Describe the problem

    Plain language, no specification required. The output of this step is a single page everyone genuinely agrees on — which is usually where the real disagreement finally surfaces.

  2. 2

    Choose the output

    A shipped feature, documentation nobody skips, or one figure that ends a forty-minute discussion. Frequently all three, in that order.

  3. 3

    Ship, then write it down

    Undocumented work gets rebuilt from scratch by whoever arrives next. Writing is not the victory lap, it is part of the delivery.

§04

API reference

Three public methods. Everything else is an implementation detail.

problembuild()applicationdocument()documentationillustrate()figure
Fig. 2 — Call graph. One input, three methods, three deliverables.

ottavio.build(product, options)

Compiles an idea into an application that real users can install.

Parameters
productstringrequired
What it should do, and for whom. Feature lists are accepted, then questioned.
options.platform'web' | 'mobile' | 'both'
Web means Next.js. Mobile means Expo and React Native, shipped to both stores.
options.stackStack
Defaults to TypeScript end to end. Negotiable, within reason.
Returns

Promise<ShippedApp> — resolves in a store listing, not in a demo video.

Throws

ScopeCreepError — Raised early and audibly. Considerably cheaper than raising it the week of the deadline.

ottavio.document(system, options)

Turns a system somebody built into something somebody else can actually use.

Parameters
systemCodebase | API | Productrequired
Entirely undocumented is the normal input, not the exception.
options.audience'developer' | 'user' | 'stakeholder'required
The same system needs three different documents. Writing one for all three produces none.
options.depth'reference' | 'guide' | 'tutorial'
A reference answers questions. A tutorial prevents them from being asked.
Returns

Documentation — measured by how far people read, never by page count.

Throws

AmbiguityError — A decision nobody has made cannot be documented. Writing it down is how those get found.

ottavio.illustrate(concept, options)

Draws the picture that makes the explanation unnecessary.

Parameters
conceptstringrequired
Architectures, flows, state machines, physical movement.
options.style'diagram' | 'schematic' | 'exploded-view'
Chosen by what the reader has to do next, not by what looks best.
options.boxesnumber
Soft limit. A figure with forty boxes is a database schema wearing a costume.
Returns

SVGElement — every figure on this page was produced by this method.

Throws

NeedsALegendError — If one figure requires a legend to be readable, it should have been two figures.

§05

Modules

Shipped and in-flight work. Status uses release channels rather than adjectives.

MyMoveset

stable · published

Platform: iOS · Android · Expo

An app for learning acrobatic moves. Every move you land becomes a collectible card, so progress is something you own rather than a number on a settings screen.

  • —Published on Google Play and the App Store.
  • —Move library with prerequisites — the graph decides what you are ready to attempt.
  • —Collection as the progress model: unlocking the card is the reward, not a badge.
movepracticelanded?yescardno
Fig. 3 — MyMoveset: the unlock loop.

VERDICT

beta · in development

Platform: Expo · React Native

A mobile game where you argue cases against AI lawyers. You win by convincing the court, which makes the real subject human judgement measured against machine judgement.

  • —Opposing counsel is a language model, so no two trials follow the same script.
  • —The theme is the mechanic: you are always being judged by something that is not human.
  • —Case files are content rather than levels — the writing is the production cost.
youAI counselcourtverdict
Fig. 4 — VERDICT: the argument loop.

TimeScrolls

alpha · in development

Platform: Expo · React Native

Photos and videos drawn as an illustrated scroll, organised by day, with your own soundtrack and notes in the margin. Built for reliving a memory rather than filing it.

  • —The scroll is the interface — one continuous illustrated timeline instead of a grid of thumbnails.
  • —Music and margin notes are first-class content, not metadata.
  • —A gallery is optimised for finding. This is optimised for remembering.
soundtrackmontuewedthufrisatsun
Fig. 5 — TimeScrolls: a day-indexed scroll.
§06

Troubleshooting

Failure modes seen often enough to deserve an entry.

The scope keeps changing.

CauseIt was never written down, so everyone is defending a slightly different version of it.

SolutionOne page, agreed before the first commit. I write it, you correct it.

Nobody reads our documentation.

CauseIt documents the code instead of the reader's task.

SolutionReorganise around what the reader is trying to do, then add one figure per concept.

The diagram is unreadable.

CauseIt shows everything at once, so it answers nothing.

SolutionSplit it by question. One figure, one answer.

Design and engineering disagree.

CauseBoth are correct, in two different documents.

SolutionBuild the prototype. It settles the argument faster than the meeting does.

§07

Changelog

Reverse order, like any other changelog.

  1. Unreleasedin progress

    TimeScrolls and VERDICT. See Modules.

  2. 3.0.0illustration

    Added figures to the toolchain. Diagrams stopped being a side effect of explaining things and became a deliverable of their own.

  3. 2.0.0documentation

    Added technical writing. Shipping code without the document that explains it was reclassified as unfinished.

  4. 1.0.0code

    Initial release. Wrote software and assumed it was self-explanatory.

§08

Support

Bug reports about this page, feature requests about your product, and unreasonable ideas all go through the same channels.