Flow is the organization and perceived progression of an article’s parts and ideas. Strong flow gives readers a logical, easy-to-follow path instead of making them reread, pause, or abandon the article. section 5.2 section 5.2.3
Use this practical test to improve an article’s flow:
- Explain the order aloud or in writing: why the article starts where it does, what comes first, what shifts next, and how each part relates to the previous one. section 5.2.3
- Shuffle disconnected parts, add sentences or paragraphs that clarify connections, and eliminate sections that do not connect to the article’s purpose. section 5.2.3
- Make headings reveal the reader’s purpose rather than exposing internal implementation terms. section 5.2.3
A high-level article path
A Zig migration-tool article can begin with the problem that motivated the project, explain the choice of Zig, present the good and bad parts of working with it, give a verdict, and invite readers to try the tool. section 5.2.3
Table 5.2 Helpful vs. unhelpful headings (view table figure)
| Unhelpful heading |
Better option |
|---|---|
| pg_fakedb |
Why we built a FakeDB <> Postgres migration tool in Zig |
| @cImport and translate-c |
How we achieved C interoperability |
| catch unreachable |
Comparing Zig’s error handling to Rust’s |
Compare headings that expose implementation details with headings that explain the reader-relevant problem, technique, or trade-off. section 5.2.3
