Documentation is the difference between a language and an idea
Many hobby languages never get past the author’s own head, even when an interpreter exists. A visitor arrives, sees a few symbols and an unfamiliar syntax, and has no way to tell whether the thing works or what to do with it. Good documentation closes that gap. It does not need to be long. For a small language, a few pages written with care are usually enough.
This article is about the experience of a reader trying your language for the first time. The formal rules, meaning the precise definition an implementer would follow, are a separate task, covered in the piece on how to write a language specification for a hobby project. Here the focus is on helping people actually get started.
Start with what the reader will do
Open with a short statement of what the language is and what makes it different, in two or three sentences. Then move quickly to something the reader can run. Many visitors decide within a minute whether to stay, so the first screen matters.
A useful order for the main page is:
- A one-paragraph summary of the idea.
- A small, complete example program with its output.
- Instructions for running it.
- A tour of the language, a few features at a time.
- Links to the full reference and the source code.
This mirrors how most people learn. They want a working example first and the complete rules later.
Show a first program early
The classic first program is the right choice for almost any language, and the Hello World program is the usual benchmark. If your language cannot print text, choose the simplest visible behavior it does have, such as counting or echoing input. Show the program, show its output, and then explain it line by line or cell by cell.
For languages with unusual layouts, such as two-dimensional ones, an annotated diagram helps a great deal. A reader who has never seen a grid language needs to be told where execution starts and which way it heads. Walking through the path step by step is a good habit, and it is the same skill as tracing by hand.
Explain each command with an example
For every command, give three things: the name or symbol, a plain-language description of what it does, and a tiny example showing its effect on the program state. A table works well for a short instruction list, with one row per command. Keep the descriptions factual. If a command behaves in a surprising way, say so directly rather than leaving it for the reader to discover.
Be explicit about the machine the commands act on. If the language has an instruction set that operates on a program stack, say how it starts, what happens when it is empty, and what values it can hold. Gaps here are the most common source of confusion, and they are also where different implementations most often disagree.
Describe the state and the edges
Readers get stuck on the same few questions, so answer them in advance.
- Where does execution begin and end?
- What does the language do with input and output?
- What happens on an error or an unknown symbol?
- How large can values and memory be?
- Are there any limits the implementation imposes?
Even when the answer is “undefined” or “the interpreter stops,” write it down. A reader who knows the rule can work around it, and a reader who does not will blame themselves.
Be honest about status
State what stage the project is in. If the interpreter is incomplete, say which parts are missing. If you are not sure whether the language is Turing complete, say that you are not sure rather than claiming it. Credit any inspirations, since many languages build on earlier ideas. Honest status notes save readers time and make the project more trustworthy.
Write for a tired, curious stranger
The best tone for hobby documentation is plain and slightly warm. Imagine the reader is smart but arriving cold, perhaps late in the evening. A few practical habits help.
- Use short paragraphs and short sentences.
- Define a term the first time it appears.
- Keep a consistent vocabulary. If you call something a “cell” in one place, do not call it a “slot” later.
- Avoid in-jokes in the reference section. Humor suits the introduction, but the rules should be readable by anyone.
- Test your instructions by following them yourself on a clean machine.
If your language is a joke, the humor can be part of the charm, but the rules still need to be clear. The relationship between the joke and the design is discussed in the article on joke languages.
Provide more than one example
A single sample program tells the reader little about how the pieces fit together. Include three or four, in increasing difficulty: a simple one, a loop or conditional, and something slightly clever. Explain what each is meant to show. If your language is stack-based or grid-based, include one example for each of the main ideas, such as branching or storing a value. Examples are also the best test of your own design, because awkward programs reveal rough edges.
Make it easy to try
Remove as many obstacles as possible.
- Provide the interpreter in a form that runs with minimal setup.
- Include a test program that proves the installation works.
- List the version of everything you tested on, without claiming more than you know.
- Offer a way to report problems.
If you can add an online runner, that helps, but it is optional. A short script and clear instructions are often enough.
Keep it up to date
When the language changes, change the documents. Mismatched documentation is worse than none, because it teaches the wrong thing confidently. A short changelog lets returning readers see what is new. If you abandon the project, say so; the next person may want to pick it up.
A short checklist
Before publishing, confirm that a stranger could do the following using only your pages: find the summary, run the first example, write a trivial program of their own, and look up an unfamiliar command. If each step works, the documentation is doing its job.