11–20 of 299 posts
Earlier quoted context omitted.
What, like "butterfly"?
Like "otherwordly", obviously. Never use "otherwordly" ph'nglui technical documentation, ngnah ymg' risk s̵͖͕͓̒̾̾ǘ̵̢̺͓͊́m̵̟͙̓̒̚m̴͉̠͖̈́͊͠o̸̞̺̻̾́̀n̵͖̻͓̓̔i̴̢͚͕̿̕͝n̴͇̞͎͒̀̚g̵̢̟͙̾̚͝ z̴̪̠̟̾̿͘a̸͇̞͙̔͌͛l̵̢̟̘͆̒g̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠
Earlier quoted context omitted.
Like "otherwordly", obviously. Never use "otherwordly" ph'nglui technical documentation, ngnah ymg' risk s̵͖͕͓̒̾̾ǘ̵̢̺͓͊́m̵̟͙̓̒̚m̴͉̠͖̈́͊͠o̸̞̺̻̾́̀n̵͖̻͓̓̔i̴̢͚͕̿̕͝n̴͇̞͎͒̀̚g̵̢̟͙̾̚͝ z̴̪̠̟̾̿͘a̸͇̞͙̔͌͛l̵̢̟̘͆̒g̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠
It was a joke, obviously. They're called adverbs.
It's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda ( https://bitecode.substack.com/p/why-not-tell-people-to-simpl... ) - Don’t use the word ‘simply’ ( https://jameshfisher.com/2017/02/22/dont-use-simply/ ) - Stop using ‘simply’ in tech instructions ( https://www.parkersoftware.com/blog/stop-using-simply-in-tec... ) - Don’t say “simply” in your documentation ( https:/…
That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".
Regarding docs: Most recent projects that i looked into and tried evaluating are very focused on the shiny parts and all the nice features it got and bells and whistles.... it sometimes reads like an ad or an sales pitch. But, I'm a sysadmin. I will be carrying operational responsibility for that thing if we decide to adopt it. I'd love to know what are the most common modes for it to break, what the cuts are where y…
Not to jump on GPT hype too much, but a good idea perhaps for an addon targeting OSS, read over issues, PRs, scrub Stack Overflow and compile a descriptive list of the most common pitfalls for a certain lib. It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.
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 it can be used at 2 different places, and depending of those places, it does completely different things. The latter is well documented, but that the brain of people cannot grok it is not.
So chatgpt will explain the same things as most of the doc, without realizing that what it needs to do is to warn humans that they are going to be confused and how to avoid it.
Humanity has a lot of implicit knowledge.*
It's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda ( https://bitecode.substack.com/p/why-not-tell-people-to-simpl... ) - Don’t use the word ‘simply’ ( https://jameshfisher.com/2017/02/22/dont-use-simply/ ) - Stop using ‘simply’ in tech instructions ( https://www.parkersoftware.com/blog/stop-using-simply-in-tec... ) - Don’t say “simply” in your documentation ( https:/…
I remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation. That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".
- It will be easy => I will guide you through it
- This will make your life easy => It will make your life easier / It will help you
- To do X, simply do Y => The most common way to get to X is first to do Y
please add "blazing fast" to this list
We simply delete the word simple and just remove the word just when we see it too. Some similar simple writing rules that we've found just improve writing overall here [0] https://styleguide.ritza.co/ritza%27s-writing-rules/Style/
please add "blazing fast" to this list