4 ms·

The article's idea of Conceptual Overviews is something I find myself missing in a lot of projects' documentation. But I'd go even further. That paragraph about

The article's idea of Conceptual Overviews is something I find myself missing in a lot of projects' documentation. But I'd go even further. That paragraph about soup from the article? Every single piece of top-level documentation for any project anywhere should start with that paragraph. What is it? Who cares or should care? What can it do? When is it a good choice? I spend a lot of time searching, trying to decide if something is worth my time to research more. Writing that paragraph (and it really does need to be just one paragraph; I guess you can split it in two if you must) is very, very valuable to your prospective users! In the hardware world everyone does this: the first page of every datasheet tries to answer these questions. That's done not because it's required, but because it helps sell parts to engineers.

spondylosaurus 3y ago
There's a great tech writing book called Every Page is Page One[1] that changed how I write docs. Its primary conceit is basically what you've described: every single doc needs to immediately orient its reader, either with an intro paragraph or seamless hyperlinks to relevant background material (or, ideally, both). If the reader lands on a page that isn't right for them, it's the writer's job to leave a trail of breadcrumbs that leads them where they need to go. To grossly oversimplify, the EPPO page structure is almost like a Wikipedia article. Imagine you end up on the page for, idk, anthrax. If you already know a bit about yucky diseases and want to learn more, you'll read on. If you get a couple paragraphs in and you're like "wait, what exactly is a bacterium?", you can click the hyperlink to the relevant article about bacteria. And if you actually wanted to read about the metal band, there's an escape hatch to redirect you to the correct location. [1] https://everypageispageone.com/ https://everypageispageone.com/

spondylosaurus 3y ago

There's a great tech writing book called Every Page is Page One[1] that changed how I write docs. Its primary conceit is basically what you've described: every single doc needs to immediately orient its reader, either with an intro paragraph or seamless hyperlinks to relevant background material (or, ideally, both). If the reader lands on a page that isn't right for them, it's the writer's job to leave a trail of breadcrumbs that leads them where they need to go. To grossly oversimplify, the EPPO page structure is almost like a Wikipedia article. Imagine you end up on the page for, idk, anthrax. If you already know a bit about yucky diseases and want to learn more, you'll read on. If you get a couple paragraphs in and you're like "wait, what exactly is a bacterium?", you can click the hyperlink to the relevant article about bacteria. And if you actually wanted to read about the metal band, there's an escape hatch to redirect you to the correct location. [1] https://everypageispageone.com/ https://everypageispageone.com/