Writing small docs is a game changer

The analogy makes no sense. Small docs aren&#x27;t like small code commits. <i>Small doc commits</i> are like small code commits, and I agree you don&#x27;t want to commit walls of text. But that&#x27;s because <i>commits are deltas</i> - they can be small, because they&#x27;re not standalone - they make no sense without the underlying (large) codebase being available to the reader.<p>So where the article proposes:<p>&gt; <i>Self-contained context</i><p>&gt; <i>Include all the necessary background so the reviewer doesn’t need to dig into other docs for clarity</i><p>That means, by necessity, that your &quot;small docs&quot; will either be so shallow and context-free that they&#x27;re not worth writing down in the first place, or will be 90%+ context copy-pasted from one &quot;small doc&quot; to another, at which point you might want to just merge them into one bigger doc and introduce a hierarchy. So, just like code.<p>(And reviews are always the bottleneck for code, too. Similarities abound.)

I have been known to author twenty-page documents in a fit of caffeine and have rarely been pleased by their reception. Circulating such epics is an office crime of sorts.<p>However, I think the quality of a document - and the time it takes to understand it - is less about the length, and more about how it&#x27;s organized. Sometimes a document will have many useful attachments, clearly labelled, that a reader can optionally review if it&#x27;s helpful. If the document has a good narrative flow, motivation, and structure, then someone can get the point quickly and skip around as they wish. Making documents very short is one way to ensure readers can follow easily, but there are ways to make it work for long documents, too.

Game changer is getting right up there with the worst of engagement bait. Since I&#x27;m on the topic, way too much &quot;everyone missed&quot; and &quot;everyone gets wrong&quot; in titles recently.

<a href="https:&#x2F;&#x2F;archive.is&#x2F;U93VS" rel="nofollow">https:&#x2F;&#x2F;archive.is&#x2F;U93VS</a>

Why not integrate them with the code à la Literate Programming?<p><a href="http:&#x2F;&#x2F;literateprogramming.com&#x2F;" rel="nofollow">http:&#x2F;&#x2F;literateprogramming.com&#x2F;</a><p>The bigger issue is that one really needs multiple types of documentation and they _all_ need to be kept in synch, and that&#x27;s the real deal-breaker (and working out an easy way to do that would be a game changer). The problem with LP of course is that the typeset source of TeX: The Program is not what most users want, and even a Literate version of Plain TeX (if it existed --- why it does not is a separate discussion) doesn&#x27;t suit most users who want instead an easy-to-use macro package (hence the popularity of LaTeX) and a template&#x2F;sample document to start with and _maybe_ a tutorial, and when there is no other recourse, a manual with examples and an index.<p><a href="https:&#x2F;&#x2F;diataxis.fr&#x2F;" rel="nofollow">https:&#x2F;&#x2F;diataxis.fr&#x2F;</a><p>put forward two axes: Action&#x2F;Cognition and Aquisition&#x2F;Application and that this results in 4 different sorts of documentation which are needed:<p>- Tutorials<p>- How-to Guides<p>- Explanation<p>- Reference<p>which feels like a bit of confusing overlap to me, and I&#x27;ve been trying to simplify it down to:<p>- readme file --- what the project does --- mostly marketing fluff with some pretty images<p>- template file(s) --- a set of examples showing all possible usages of the overall project, _and_ including a valid example of each possible command where it should be possible for a user to select a template matching the specifics of their project and get started<p>It is expected that most users will only avail themselves of those two pieces of documentation<p>- manual which includes a command glossary and an index --- again, the command glossary includes a valid example of usage for each command<p>Which exists mostly for tech support purposes --- when queried on usage the reply is usually, &quot;See sub-section X.Y, paragraph Z on pg. ###&quot;<p>- typeset source code with comments --- which _should_ only need to be seen by developers working on the code

I like the idea. It has it&#x27;s downsides too but it&#x27;s way better than either a wall of text or nothing at all.<p>I know a guy who writes a wall of text. He literally calls it a wall of text. No one reads it and he gets really angry.

Server reports insufficient storage. Web Archive also didn’t archive the URL yet.

I disagree with smaller docs being easier to write. Quite the opposite, it is easy to write longer text, which then requires more effort from the reader to understand it.<p>To write shorter text, you must put in the effort beforehand to compact, crystallize and organize the ideas. Each reader then doesn&#x27;t have to do that themselves in their heads.

Smaller docs (and more of&#x27;em) throws up the problem of findability. The author lists the usual &quot;fixes&quot; but I do not find it convincing.<p>This is where I&#x27;d expect an A.I.-powered tech support chat system to help. Then smaller-is-better might really work well. Just be sure to supply some helpful+necessary context (intro&#x2F;outro) when directing me to the mini doc. And if there&#x27;s going to be A.I. then it might help with the items on the author&#x27;s list too (doc organisation, doc linking, doc hygiene).

These points are what I like about wiki format for tech projects.

Some docs are better than none, but writing less is not easy.

Writing docs for software is something that in theory LLMs should be great at. It&#x27;s clear they are useful, and that developers generally do not like writing them, and that LLMs are good at condensing complex information into easier to understand text.

Game changers are game changers, and they&#x27;re healthy once in a while. Shifting your process challenges different muscles and surfaces different talents. Embrace fads, try things out, retain your favorite bits.

I remember discussing docs length with some seasoned technical writers (TW) when I was a junior TW. I believe I was expressing doubt in the idea that we should always aim for short docs. They of course had a wise and pithy summary of the correct (IMO) course of action: make docs as short as possible, and no less.<p>Sometimes you have a meaty topic that takes many words to cover comprehensively and accurately. Don&#x27;t beat yourself up over it. Providing full and complete information is usually more important than some arbitrary limit on length.<p>With that said, it&#x27;s also a fundamental truth that there almost always ways to make your docs more concise without a loss in information. And in general this is worth doing because it really does improve the odds that people will read the docs.<p>The article&#x27;s prescription to use short, self-contained pages that link extensively to each other is right out of the playbook of my favorite TW book ever: <i>Every Page Is Page One</i> (don&#x27;t judge this book by its cover, literally)<p>I would have liked to see the article focus on more of the SEO and LLM arguments for short docs, which I think are compelling. Short docs basically give you that Stack-Overflow-style SEO boost, because the main content is tightly relevant to the page title. Small docs are easier to embed, and probably easier to do automated updates on with text generation models.

I like how a site called bufferbuffer.com is down for insufficient storage

Tool long didn&#x27;t read meme just popped in my mind.

Whoops, looks like we managed to ddos this website.

small docs are great, but only if easily searchable