Why writing small docs is a game changer
44 comments
·March 4, 2025TeMPOraL
ricardobeat
Looks like you got stuck on that first paragraph. The author doesn’t even make an analogy between small commits and small docs, it’s just used as a hook for the intro.
null
tibbar
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.
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's organized. Sometimes a document will have many useful attachments, clearly labelled, that a reader can optionally review if it'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.
piva00
I completely agree, it all hinges on the quality of the document.
I really don't mind twenty-page docs when they are well-structured, have a clear drill-down from less details to more details through the relevant parts, documents where I feel are guiding my reading towards the important bits I need at the time, and making me comfortable to get into the weeds when I feel prepared enough by understanding what's the general point of the document. It's actually pleasant to read those.
The issue is: almost nobody has (or puts in) the time to properly edit a twenty+ pages document to make it pleasant to read, I've been guilty of that too in the past and do understand it usually comes from having so much of the context in one's own head that it gets lost taking the view of someone reading all the context for the first time.
I've strived to be better at it for years and it isn't an easy skill to learn but in a larger organisation it's immensely valuable to save everyone else's time.
remoquete
> almost nobody has (or puts in) the time to properly edit a twenty+ pages document to make it pleasant to read
That's why technical writers and editors exist.
jdwithit
They exist, and are very valuable, but I've never worked at a company that employed even one full time technical writer. If I go on a caffeine bender and write the 20 page doc OP described, nobody is coming back around to clean that up for me. At best some peers might tell me "hey, great effort there, but could you cut the word count by 75%?" Access to full-time professional editors seems like a luxury of very large organizations.
pinoy420
[dead]
WillAdams
Why not integrate them with the code à la Literate Programming?
http://literateprogramming.com/
The bigger issue is that one really needs multiple types of documentation and they _all_ need to be kept in synch, and that'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't suit most users who want instead an easy-to-use macro package (hence the popularity of LaTeX) and a template/sample document to start with and _maybe_ a tutorial, and when there is no other recourse, a manual with examples and an index.
put forward two axes: Action/Cognition and Aquisition/Application and that this results in 4 different sorts of documentation which are needed:
- Tutorials
- How-to Guides
- Explanation
- Reference
which feels like a bit of confusing overlap to me, and I've been trying to simplify it down to:
- readme file --- what the project does --- mostly marketing fluff with some pretty images
- 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
It is expected that most users will only avail themselves of those two pieces of documentation
- manual which includes a command glossary and an index --- again, the command glossary includes a valid example of usage for each command
Which exists mostly for tech support purposes --- when queried on usage the reply is usually, "See sub-section X.Y, paragraph Z on pg. ###"
- typeset source code with comments --- which _should_ only need to be seen by developers working on the code
namaria
Game changer is getting right up there with the worst of engagement bait. Since I'm on the topic, way too much "everyone missed" and "everyone gets wrong" in titles recently.
pinoy420
[dead]
dieulot
lyu07282
Has someone automated this yet? I mean archive every post then post the archive link if the post is "hugged-to-death"?
null
m_mueller
another WP site that goes down with the tiniest amount of load. seen it too many times.
globalnode
any website that asks me to prove im not a robot can f off, i dont need to see it that badly - unless i do, but hopefully thats rare.
megadata
I like the idea. It has it's downsides too but it's way better than either a wall of text or nothing at all.
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.
chefandy
Yeah— I hate coming across a doc that’s less like a technical reference, or even a tutorial, and more like a treatise on the philosophy behind their technical decisions. I know it’s a bit controversial, but I find Python’s docs like that. They’re very thorough and great for reading about how the Python interpreter does things, and why, but if you need to quickly reference something about a function or a quick reminder about syntax you infrequently use, they’re miles behind MDN’s JavaScript docs, any of the .NET language docs I’ve used, Elixir’s, and even PHP (though the lack of versioning when I used it seemed dangerous).
readthenotes1
One of the enduring truths is that most people don't read. We ignore signs that say "don't" and advisories that say "do". If there's reading materials for a meeting, plan to spend the first half trying to recap them.
Tldr: put the tldr at top for goodness sake!
bArray
Writing docs for software is something that in theory LLMs should be great at. It'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.
jampekka
If you can get docs from an LLM, why not just use LLM interactively?
That's how I use them anyway, I just ask how to do X with library Y and then ask for further info if needed. If that fails, go for the source code.
huijzer
Server reports insufficient storage. Web Archive also didn’t archive the URL yet.
djmips
Doc wasn't small enough.
TZubiri
Anything more than 0 is too much.
Why would u need disk space to serve an http req?
gregoryl
It likely writes request logs to disk as part of the request!
echoangle
Logging
mackopes
Damn. Here’s the upvote
raffraffraff
Now it's "Error establishing a database connection"
People can complain all they want about CDNs running the internet, but my wife's crappy little website hasn't been offline since I left broke it myself.
nicky0
You say CDN but you're really talking about static web servers in general.
null
ashycre
These points are what I like about wiki format for tech projects.
remoquete
Some docs are better than none, but writing less is not easy.
namaria
"I didn't have time to write a short doc, so here's a long one"
bayindirh
Distilling something to a short document is not easy. I write "live" docs, i.e. during the process itself, on a separate document. They become long, but they stay linear and searchable. They are very good for returning back and doing the same thing or improving the doc itself.
However, if I want to distill it to a smaller doc, I'd need to spend another day to make it perfect, and I don't have time, unfortunately.
namaria
I guess I managed to say the same as you but with less words. /s
I wasn't mocking op, I was referencing Mark Twain
remoquete
More common than you'd think...
shric
I like how a site called bufferbuffer.com is down for insufficient storage
The analogy makes no sense. Small docs aren't like small code commits. Small doc commits are like small code commits, and I agree you don't want to commit walls of text. But that's because commits are deltas - they can be small, because they're not standalone - they make no sense without the underlying (large) codebase being available to the reader.
So where the article proposes:
> Self-contained context
> Include all the necessary background so the reviewer doesn’t need to dig into other docs for clarity
That means, by necessity, that your "small docs" will either be so shallow and context-free that they're not worth writing down in the first place, or will be 90%+ context copy-pasted from one "small doc" to another, at which point you might want to just merge them into one bigger doc and introduce a hierarchy. So, just like code.
(And reviews are always the bottleneck for code, too. Similarities abound.)