91–100 of 299 posts
One of the best pieces of advice I learned in high school from an incredible English teacher: when doing technical, avoid "-ly" words entirely. It has always been solid advice and has rarely led me astray.
> avoid "-ly" words I hope this isn’t the actual advice you were given. They are called adverbs.
$ bin/rails generate scaffold user name email login
$ bin/rails --generate=scaffold --user=name --email=login
$ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name
$ bin/rails --generate --scaffold=user --name=fullname --email=address --login=login_name
https://astralcodexten.substack.com/p/give-up-seventy-percen...
This is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
I see it differently. If you are writing documentation for a system you know a lot about, things are completely simple for you right then right there. But as we all know in 6 months you'll look at your own code and think "who the ... wrote this?". So avoiding the word "simple" isn't about accommodating the 5% of your least intelligent users and dumbing down the content, but the > 90% who are not so into the topic as…
Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…
Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…
I agree with your point. Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things. It's important to remember that the code is not a reflection of ourselves, and not everyone will be pleased with it. Some will provide good guidance, while others will not. Therefore, we should remove our ego from the code. Code is like a lollipop that we enjoy, but then discard once…
If there's one thing I've learned in life, anytime you see "Nowadays" or "these days" or something similar, you can be guaranteed that whatever statement follows it is a universal truism about the human condition that recency has no bearing on.
People are sensitive about their work. And sensitive to how we communicate together. Always have been. Always will be.
While we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like: $ bin/rails generate scaffold user name email login Which is it? $ bin/rails --generate=scaffold --user=name --email=login Or: $ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name Or: $ bin/rails --generate --scaffold=user --name=fullname --email=address --login=…
Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…
Earlier quoted context omitted.
The problem is a lot of it is not publicly available. E.G: I asked chat gpt to help me install Python on Ubuntu 22.04, and it failed miserably. Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet. And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because i…
There's an explicit caveat on chat gpt: limited knowledge of the world and events after 2021. You're asking about 22.04.
I would go one step further. If we are talking about CLI tool usage - the cli should have two modes. One interactive using gum or some similar library. Once complete - it should output the non-interactive equivalent CLI command.
The interactive run should give short explanations to help learn the tool.
The takeaway point is that docs are partially advertisements - and if you don't want to lose people - your docs have to be carefully crafted.