- Posted by: Joanna Davidson
- Category: Content Strategy
Different readers need different answers. A developer evaluating an integration, a user learning an application and a partner reviewing your business should not have to search the same long document for everything.
Start with the reader’s task, then choose the format. The following documents can work together for a Web3 application, DeFi protocol or blockchain infrastructure company. You do not need every format simply because another team has one.
White paper: explain the product and its rationale
A white paper gives readers a structured account of the problem, proposed approach, architecture and relevant business context. Explain why the approach makes sense, what exists today and what remains under development.
There is no useful universal page count. Include enough detail to support an informed evaluation, and link to more specialised material rather than repeating it. The opening overview should stand on its own for readers who need the main points first.
Technical specification or yellow paper: define the mechanics
A technical specification is for readers who need precision about how the system behaves. Depending on the project, it may cover algorithms, data structures, protocol rules, assumptions or mathematical reasoning. Some teams call this a yellow paper.
Work with the engineers responsible for the system. Define terms consistently, distinguish requirements from explanations, and keep the specification aligned with the implementation. Diagrams should clarify the model without hiding exceptions or failure cases.
Developer documentation: help someone build
Developer docs support practical tasks. A quickstart should name the prerequisites, guide the reader to a first working result and show how to check it. Reference pages then describe APIs, SDKs, parameters, responses and supported versions.
Include troubleshooting for common errors and links to deeper explanations. Test examples against the versions you document, and identify whether instructions use a local environment, test network or production service.
User guides: help someone complete a task
User-facing documentation should follow the application’s actual workflow. Explain what the user needs, the steps to take and how to recognise completion. Define unfamiliar terms where they appear.
For a DeFi interface, relevant fees, approvals, dependencies and risk information should be easy to find. Clear writing should help people understand a decision, rather than pressure them into taking an action.
One-page overview: support an initial conversation
A one-pager introduces your business, intended audience, core use case and next step. It can support an event, partnership discussion or sales conversation. Keep the document focused enough to scan and link to the technical detail.
Use a readable layout for both digital and printed versions. Do not squeeze an entire white paper into tiny text to meet an arbitrary length.
Light paper: provide a concise introduction
A light paper sits between an overview and a detailed white paper. It explains the central idea and enough supporting context for readers deciding whether to investigate further.
Focus on the questions your audience asks first. Keep terminology and current-versus-planned feature descriptions consistent with your longer documents.
Build a connected set of resources
Give each document an owner, a clear purpose and a route to the next useful resource. Review related pages when a release changes the product. A small, accurate documentation set is easier to maintain than several overlapping documents that disagree.
Read our technical white paper review checklist, or explore our Web3 documentation and white paper writing services. Tell us about your audience and we can help shape the right material.
