This page provides an overview of how best to contribute to Cloudflare’s documentation.
Whether you’re adding a new page or just updating an existing one, it’s important to understand the philosophy behind our choice of information architecture.
Divio’s documentation system
- How-to guides
- Technical reference
For convenience, we’ll reproduce a key table here:
|oriented to||learning||a goal||information||understanding|
|must||allow the newcomer to get started||show how to solve a specific problem||describe the machinery||explain|
|its form||a lesson||a series of steps||dry description||discursive explanation|
|analogy||teaching a small child how to cook||a recipe in a cookery book||a reference encyclopaedia article||an article on culinary social history|
The key insight is that by breaking content up in this way, each of the four types of documentation only have one job, and they can really nail it.
The division makes it easier for authors to determine where new material should go, and makes it easier for readers to consume because the content is clear and practical.
Cloudflare Workers docs
The first Cloudflare product to adopt this system was the Cloudflare Workers docs.
Within Cloudflare Workers, the division is as as follows:
- Tutorials – The section.
- How-to guides – Though a work-in-progress¹, and .
- Technical reference – Three² components: , , and .
- Explanation – The section.
¹ certainly do “show how to solve a specific problem”, but as currently written, they don’t always provide a clear “series of steps”, similar to a recipe in a cookbook. This is something we’d like to improve over time.
² Prior to , all three of these sections were consolidated under a top level “Reference” folder. Ultimately we decided to remove this nested hierarchy to improve discoverability. We recognize the impact of the loss of the word “Reference” from the navigation, but felt the tradeoff was worth it.
Cloudflare documentation should be practical and approachable.
Use short words, short sentences, and short paragraphs.
Focus on clearly documenting the “80%” case first. Complete documentation is important, but don’t let perfection be the enemy of the good.
Avoid hierarchy. When possible, it’s better to flatten hierarchy as much as possible. Practically, this often means re-wording headings to avoid h4s and h5s, and instead add a few more h2s and h3s. Flatter hierarchies are conceptually easier to understand and generally increases discoverability.
Consistency trumps style. When in doubt, match your content to the documentation around it. Raise an issue on GitHub when something feels off.
Writing technical reference
Structure the documentation around the codebase. When documenting a set of APIs, for example, name and organize the files to match the codebase’s naming and folder structure. This helps ensure consistency when communicating with users, who may see and interact with codebase, and helps maintainers see where documentation is missing or needs to be updated.
Do nothing but describe. The only job of technical reference is to describe, as clearly and completely as possible. Anything else (explanation, discussion, instruction, speculation, opinion) is a distraction and will make it harder to follow.
Be accurate. Keep documentation up-to-date.