41–50 of 455 posts
Earlier quoted context omitted.
Linux is a pretty valuable example of such astronautics. Also things like TCP... I hope you don't die on a hill tho, not anytime soon at least.
Hilariously incorrect take. Zero CPP in the Linux kernel. Torvalds openly hates CPP. EDIT: thank you for your well wishes though :)
When I first started writing some internal docs/tutorials at work, I was new to Linux. So I generally took the time to include tangents into explaining fairly basic Linux concepts, because they were new to me. They were rough edges I had to get past so I wanted to help others do the same.
Five years and a shit load of Linux experience later, I don't do that anymore. That stuff has become so second nature to me that it just doesn't even occur to me anymore. And I just don't have the damn time. If I had to stop to explain what cat or sudo or | mean in every doc I write I wouldn't have time to get anything done.
Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. They’re more like academic papers (peer-to-peer communication of new discoveries) than they are like a pop sci book or show meant for a general audience. And that’s okay! Great even! As a fellow peer I benefit greatly from those tutorials. Sometimes even from my own notes published and forgotten years ago. This is w…
My son is 17 and very interested in programming. Had to explain to him public, private, internal, and also static the other night.
I then joked, you should ask your teacher about recursion tomorrow. He's with his mom this weekend, but I'm anxiously awaiting hearing how that went.
What I would give for people to approach documentation in a more empathetic way; tell me what something is for, what problem it solves vs other competing solutions such as X or Y, whether it's still the best solution or in maintenance mode because another tool has become dominant.
Give me the tools to construct my own pros and cons matrix, without assuming that I'm an expert. Put five minutes into asking yourself "what questions are people likely to have, even if they aren't sure exactly what to ask" and write that down.
I'll never understand how someone can spend months or years of free time building something, but then actively sabotage it by not making it easy for people to realize that they've found what they are looking for.
It's also really valuable to keep perspective on the different kinds of documentation. https://diataxis.fr/ is a really solid starting point for anyone aspiring to create better docs.
Earlier quoted context omitted.
> Most tutorials are not for non-developers, they’re for other developers who are also in the ecosystem. To me eye, most tutorial nowadays are so a developer can put "made public contribution to " on their resume or quarterly evaluation rather than helping other developers. I'd be even happier if the original writer would simply come back 3 months later and retrace their own directions. That would make the tutorial v…
Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing. Examples are often the best way to do documentation, sadly.
One of the things I've tried to teach people I've mentored over the past few decades is the principle of "Sharing is better than assuming." If you know something, share it with other people. Don't assume that they know something. If they do know, and you tell them, then you've only really confirmed what they already knew. If they don't know whatever it is you've helped them immensely and made whatever it is much more…
I have encountered a number of people who exhibit startling hostility at being told something they were already aware of. While I cannot currently recall a specific example, I strongly suspect I have previously felt this way myself. While sharing may be better than assuming when only considering the local optimum, if your signal to noise ratio is bad enough, you will face an impairment to communication that simply wo…
If the user achieves what they need with minimal stress/guesswork/ambiguity, the docs pass. If not, note every single place they fail, address each one, and repeat with a new user.
I've used FAANG docs that don't come close to passing the above criteria.
I've been incredibly grateful my org set this high bar. Especially when using docs for critical tech I only use from time to time (where I forget lots of it). Saves meetings, support inquiries, and video calls, because the user can self-serve.
Earlier quoted context omitted.
HPC? Windows NT? GCC? Video games? I'm a veteran C programmer with a deep dislike of C++, but to say it's not used for valuable software is just wrong.
The language committee only makes it harder and more astronauty every year. How many Unreal Engine developers from 2007-2013 understand CPP20/23?
I was a C++ developer for a decade and knew a fair amount of the C++13 spec but never needed to use even half of it in production. I've been a Java developer for years and don't know 10% of the standard library there. That doesn't make either language poorly designed by itself.