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.)
ricardobeat 122 days ago [-]
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.
TeMPOraL 122 days ago [-]
I disagree. I believe it's the load-bearing analogy that's carrying all the ideas in the article. Consider e.g. the sections "The benefits of small docs" and "Avoid blocking yourself during reviews" - they're mostly about workflow. They apply to changesets, not the artifact itself.
I feel like there's an implied assumption in the article, that documents are always submitted and reviewed wholesale, so to get the benefits of small commits, you need to make the document small enough to qualify as a small commit. If that's the idea, then I disagree with it.
122 days ago [-]
tibbar 122 days ago [-]
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 122 days ago [-]
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.
tibbar 121 days ago [-]
I was thinking about the article's idea of having a lot of tags to organize all the little documents, and I think I see what they're missing. Often, the most important part of writing is providing a coherent structure and mental model for a complex, messy system. Tags are not a good way of doing that. If you only write small documents and then have a hodge-podge of tags to group them together, you seriously risk missing the forest for the trees. People need to understand how complex systems fit together, not just read short descriptions of all the engine parts.
remoquete 122 days ago [-]
> 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 122 days ago [-]
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.
remoquete 121 days ago [-]
I don't know. I work for a B-series startup and I'm a docs engineer.
hinkley 121 days ago [-]
"Assigning homework." I've heard it called.
If you must write 20 pages of text, split them up into eight documents that are all reasonable.
pinoy420 122 days ago [-]
[dead]
namaria 122 days ago [-]
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.
slowmovintarget 121 days ago [-]
Use Chat Gippety to write your blog posts, get Chat Gippety titles.
For engagement! (Note to self: create new "For the King!" meme...)
Also be sure to include at least one misspelling, and one objectively wrong take, because any publicity is good publicity.
hinkley 121 days ago [-]
Top Ten Game Changers That Everyone Gets Wrong
bayindirh 121 days ago [-]
Bloggers hate one this weird trick that everyone gets wrong but it's a game changer and considered harmful.
Peak-bait title.
Why don't someone writes a "bait" title generator? Lemme ping someone...
latexr 121 days ago [-]
> Why don't someone writes a "bait" title generator?
I’d prefer a bait title detector and replacer. Or better yet, an eraser, since bait titles accompany shallow uninteresting articles more often than not and we shouldn’t be giving them the clicks anyway.
bayindirh 121 days ago [-]
I suggested that activity as a fun and satire exercise, like how it's done in early 2000s.
On a more serious note, I currently prefer to skip bait titles everywhere. I even changed the paper I read to another one which doesn't use {rage,click,etc}-bait titles.
Mental health and self-care is important.
hinkley 120 days ago [-]
You guys all missed out on the original grunge band name generator.
bayindirh 120 days ago [-]
I vaguely remember something like that, but what I miss is flash based soundboards, compiled as Windows EXE files. They were fun.
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
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 122 days ago [-]
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).
hinkley 121 days ago [-]
If you hit a point in the writing where you say, "the point is" or "long story short" and the scroll indicator is lookin' mighty small, block select everything above and put it into another text editor in case you want to cherry pick a few good bits and just start over.
If you start any sentence to defend yourself with, "It was hard to write, it should be" you the problem.
readthenotes1 122 days ago [-]
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!
D-Coder 121 days ago [-]
I've seen "BLUF": "Bottom Line Up Front."
megadata 122 days ago [-]
Agree. It's funny how the internet gang reinvented the summary by calling it tldr. But on the other hand tldr is often like a summary of the summary.
Having a good summary at the top at least doubles the usefulness of your document
huijzer 122 days ago [-]
Server reports insufficient storage. Web Archive also didn’t archive the URL yet.
djmips 122 days ago [-]
Doc wasn't small enough.
megadata 122 days ago [-]
He forgot to write a small doc for the server requirements.
darig 122 days ago [-]
[dead]
TZubiri 122 days ago [-]
Anything more than 0 is too much.
Why would u need disk space to serve an http req?
gregoryl 122 days ago [-]
It likely writes request logs to disk as part of the request!
TZubiri 122 days ago [-]
I'm having trouble imagining a system where inability to log causes a failure to serve the request instead of just not logging the request.
Surely generic servers like apache, nginx handle that case gracefully.
It probably isn't a handcoded server in python or something like that, because it is returning a precise status code and message instead of just converting a write() exception to a generic 500.
It's an amazing feat of engineering to get this so wrong.
Joker_vD 122 days ago [-]
Why on earth would you want to keep serving requests you can't log?! That makes about as much sense as serving empty pages when your DB/file storage with site contents goes away.
TZubiri 121 days ago [-]
Is this trolling?
So that users can read the content...
Joker_vD 121 days ago [-]
No, I am serious. If you bother to log the requests, then obviously you care about the logs being accurate and complete. Conversely, if you don't care about the logs, just turn them off entirely.
> So that users can read the content...
Does e.g. your authorization middleware adopt the same stance?
TZubiri 121 days ago [-]
" If you bother to log the requests, then obviously you care about the logs being accurate and complete. Conversely, if you don't care about the logs, just turn them off entirely"
Try to log, if not, serve anyways, anything else is insane for a static website.
Take a law firm's website, you would rather not serve the webpage because the disk is full? I'm getting all your clients bro.
echoangle 122 days ago [-]
Logging
mackopes 122 days ago [-]
Damn. Here’s the upvote
raffraffraff 122 days ago [-]
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 122 days ago [-]
You say CDN but you're really talking about static web servers in general.
122 days ago [-]
kennu 122 days ago [-]
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.
To write shorter text, you must put in the effort beforehand to compact, crystallize and organize the ideas. Each reader then doesn't have to do that themselves in their heads.
euroderf 122 days ago [-]
Smaller docs (and more of'em) throws up the problem of findability. The author lists the usual "fixes" but I do not find it convincing.
This is where I'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/outro) when directing me to the mini doc. And if there's going to be A.I. then it might help with the items on the author's list too (doc organisation, doc linking, doc hygiene).
hinkley 121 days ago [-]
Smaller docs result in more introductory sentences and people are worse at writing introductory sentences than they are at writing documentation. I just lost an argument with as OSS maintainer who insisted that the opening paragraph to an important doc had to remain technically precise despite being completely impenetrable to most of the users who would land on it (likely entry point from google, shortly after picking up the library).
An attempt to meet the needs of people following search engine links right into the middle of documentation.
This is where I wonder if an A.I. could provide missing introductory context, based on the conversation that got you to the doc.
hinkley 120 days ago [-]
That was effectively the problem. There are pages that describe concepts but search engines take you right to the API which introduces related jargon words that are neither defined nor hypertext.
But I fear this is a bridge too far for a domain that didn’t bother making DevEx a thing until a few years ago.
euroderf 120 days ago [-]
Good point about jargon. So every page needs a link to (or a listbox of) glossary.
hinkley 120 days ago [-]
Or just use industry standard words and introduce the jargon deeper down. Like in function arguments.
ashycre 122 days ago [-]
These points are what I like about wiki format for tech projects.
remoquete 122 days ago [-]
Some docs are better than none, but writing less is not easy.
namaria 122 days ago [-]
"I didn't have time to write a short doc, so here's a long one"
bayindirh 122 days ago [-]
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 122 days ago [-]
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
bayindirh 122 days ago [-]
I just wanted to extend what you said, and give a real world example to support you. I didn't think you mock the OP either.
Who knows, maybe longer docs reduce misunderstanding, like how error correction reduces problems as the information moves through mediums. :)
namaria 121 days ago [-]
Got you, I was a bit on edge from previous not so fun exchanges on another thread.
I go by Feynman's logic: if you can't explain it simply you don't understand it. Redundancy doesn't seem to me to be a good thing in documentation. Would make it harder to parse and maintain...
latexr 121 days ago [-]
> Redundancy doesn't seem to me to be a good thing in documentation. Would make it harder to parse and maintain
And increases the word count, making it less likely someone will even begin reading it.
bayindirh 121 days ago [-]
You don't need to repetitiously write things over and over again. You can link or reference the relevant parts with clickable links.
This way your document will look compact and neat while having all the necessary information contained in everywhere and every part of your documentation.
Also interconnected documents reduce the burden of repeatedly updating duplicate parts. You reference or link it, and update and change it for once.
Note: Yes, I have intentionally and knowingly written that way.
bayindirh 121 days ago [-]
> Got you, I was a bit on edge from previous not so fun exchanges on another thread.
Ah, that happens, no problems on my side whatsoever.
> I go by Feynman's logic: if you can't explain it simply you don't understand it.
That's true, but in reality it needs a couple of passes to distill down, which needs time. An example of a live document I have written can be given as [0].
Can it be better? By miles. How much time does it need? An amount I don't have right now. "When you're poor, everything is expensive" works for time, too. So, I try to do my best when I have time, and polish it later when I have additional time for it.
> In conclusion, Blaise Pascal wrote a version of this saying in French and it quickly moved into the English language. The notion was very popular and variants of the expression have been employed by other notable figures in history. The saying has also been assigned to some prominent individuals without adequate factual support.
remoquete 122 days ago [-]
More common than you'd think...
bArray 122 days ago [-]
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 122 days ago [-]
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.
jeltz 122 days ago [-]
Because you need to proof read it and correct issues. Every time I have tried using LLMs to document something non-trivial there have been fundamental misunderstandings. And those are easy for the orginal author of the code to fix.
blueboo 122 days ago [-]
Game changers are game changers, and they'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.
kaycebasques 122 days ago [-]
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.
Sometimes you have a meaty topic that takes many words to cover comprehensively and accurately. Don't beat yourself up over it. Providing full and complete information is usually more important than some arbitrary limit on length.
With that said, it'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.
The article'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: Every Page Is Page One (don't judge this book by its cover, literally)
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.
shric 122 days ago [-]
I like how a site called bufferbuffer.com is down for insufficient storage
tmaly 122 days ago [-]
Tool long didn't read meme just popped in my mind.
tmikus 122 days ago [-]
Whoops, looks like we managed to ddos this website.
qwertox 122 days ago [-]
This is a bit more strange. If it's an insufficient storage problem I'm wondering what is getting stored per-request.
ryancouto 122 days ago [-]
small docs are great, but only if easily searchable
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.)
I feel like there's an implied assumption in the article, that documents are always submitted and reviewed wholesale, so to get the benefits of small commits, you need to make the document small enough to qualify as a small commit. If that's the idea, then I disagree with it.
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.
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.
That's why technical writers and editors exist.
If you must write 20 pages of text, split them up into eight documents that are all reasonable.
For engagement! (Note to self: create new "For the King!" meme...)
Also be sure to include at least one misspelling, and one objectively wrong take, because any publicity is good publicity.
Peak-bait title.
Why don't someone writes a "bait" title generator? Lemme ping someone...
I’d prefer a bait title detector and replacer. Or better yet, an eraser, since bait titles accompany shallow uninteresting articles more often than not and we shouldn’t be giving them the clicks anyway.
On a more serious note, I currently prefer to skip bait titles everywhere. I even changed the paper I read to another one which doesn't use {rage,click,etc}-bait titles.
Mental health and self-care is important.
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.
https://diataxis.fr/
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
https://orgmode.org/worg/org-contrib/babel/intro.html
+
https://orgmode.org/manual/Extracting-Source-Code.html
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.
If you start any sentence to defend yourself with, "It was hard to write, it should be" you the problem.
Tldr: put the tldr at top for goodness sake!
Having a good summary at the top at least doubles the usefulness of your document
Why would u need disk space to serve an http req?
Surely generic servers like apache, nginx handle that case gracefully.
It probably isn't a handcoded server in python or something like that, because it is returning a precise status code and message instead of just converting a write() exception to a generic 500.
It's an amazing feat of engineering to get this so wrong.
So that users can read the content...
> So that users can read the content...
Does e.g. your authorization middleware adopt the same stance?
Try to log, if not, serve anyways, anything else is insane for a static website.
Take a law firm's website, you would rather not serve the webpage because the disk is full? I'm getting all your clients bro.
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.
To write shorter text, you must put in the effort beforehand to compact, crystallize and organize the ideas. Each reader then doesn't have to do that themselves in their heads.
This is where I'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/outro) when directing me to the mini doc. And if there's going to be A.I. then it might help with the items on the author's list too (doc organisation, doc linking, doc hygiene).
An attempt to meet the needs of people following search engine links right into the middle of documentation.
This is where I wonder if an A.I. could provide missing introductory context, based on the conversation that got you to the doc.
But I fear this is a bridge too far for a domain that didn’t bother making DevEx a thing until a few years ago.
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.
I wasn't mocking op, I was referencing Mark Twain
Who knows, maybe longer docs reduce misunderstanding, like how error correction reduces problems as the information moves through mediums. :)
I go by Feynman's logic: if you can't explain it simply you don't understand it. Redundancy doesn't seem to me to be a good thing in documentation. Would make it harder to parse and maintain...
And increases the word count, making it less likely someone will even begin reading it.
This way your document will look compact and neat while having all the necessary information contained in everywhere and every part of your documentation.
Also interconnected documents reduce the burden of repeatedly updating duplicate parts. You reference or link it, and update and change it for once.
Note: Yes, I have intentionally and knowingly written that way.
Ah, that happens, no problems on my side whatsoever.
> I go by Feynman's logic: if you can't explain it simply you don't understand it.
That's true, but in reality it needs a couple of passes to distill down, which needs time. An example of a live document I have written can be given as [0].
Can it be better? By miles. How much time does it need? An amount I don't have right now. "When you're poor, everything is expensive" works for time, too. So, I try to do my best when I have time, and polish it later when I have additional time for it.
[0]: https://notes.bayindirh.io/notes/Hardware/Installing+a+Home+...
> In conclusion, Blaise Pascal wrote a version of this saying in French and it quickly moved into the English language. The notion was very popular and variants of the expression have been employed by other notable figures in history. The saying has also been assigned to some prominent individuals without adequate factual support.
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.
Sometimes you have a meaty topic that takes many words to cover comprehensively and accurately. Don't beat yourself up over it. Providing full and complete information is usually more important than some arbitrary limit on length.
With that said, it'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.
The article'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: Every Page Is Page One (don't judge this book by its cover, literally)
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.