Just Simply – Stop saying how simple things are in our docs
1–10 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#2One 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.
Re: Just Simply – Stop saying how simple things are in our docs
#3It'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://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-...)
And I strongly agree. It can be so discouraging to fail at something you should "simply" do.
But to be fair to the technical writers, it's easy to write that way without noticing, even after proof reading. This should be automatized by writing tools.
Also, while it's mildly irritating, there are worse things in life.
Yet as the first link about the python ecosystems notes, it usually hides a bigger problem: many devs are too good to be helpful.
Re: Just Simply – Stop saying how simple things are in our docs
#4Regarding 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 you could swap in your code, resource usage, update cycles and stability guarantees of these updates. Existence of a downgrade path (looking at you, kubernetes!). Ideally you'd know ahead if you are getting something robust where you can safely take a week off without any risks or something that needs to keep a firefighting team on-call for the rest of its lifetime.
I think a lot more needs to be done on the docs than omitting some words...
Re: Just Simply – Stop saying how simple things are in our docs
#5We 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]
Re: Just Simply – Stop saying how simple things are in our docs
#6+1 to the article.
I’ve noticed this more recently. Ironically, it seems to be more common with coding communities known for their welcoming spirit and helpful nature, for example Rust.
Gratuitous repetition of how easy something is can make it feel harder when understanding is not immediate.
Re: Just Simply – Stop saying how simple things are in our docs
#7If simple things like running a command isn't simple for you then the docs were written for a different target audience than you. Just because I'm checking the docs it doesn't mean that something isn't simple. It is just impossible for me to know or remember everything about everything even if some of those things are simple.
If you aren't the target audience that doesn't mean you can't use it, you just might end up needing to ask for help from someone who is from the target audience.
Re: Just Simply – Stop saying how simple things are in our docs
#8One 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.
What, like "butterfly"?
Re: Just Simply – Stop saying how simple things are in our docs
#9Regarding 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.
Re: Just Simply – Stop saying how simple things are in our docs
#10One 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.
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̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠