If someone’s having to read your docs, it’s not “simple”
justsimply.dev
If someone’s having to read your docs, it’s not “simple”
1–10 of 146 posts
Re: If someone’s having to read your docs, it’s not “simple”
#2Another thing you should not do is name things “fast”. It will end up not being fast (esp when you find the next faster thing) or else someone will find security holes in it.
Re: If someone’s having to read your docs, it’s not “simple”
#3Another word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.
Re: If someone’s having to read your docs, it’s not “simple”
#4Another thing you should not do is name things “fast”. It will end up not being fast (esp when you find the next faster thing) or else someone will find security holes in it.
Agreed. Same thing with "Smart".
Re: If someone’s having to read your docs, it’s not “simple”
#5Brought to you by "just simply dot dev"
Re: If someone’s having to read your docs, it’s not “simple”
#6Another word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.
Years ago, I read Michael Crichton's autobiography "Travels". In that book there is one particular part that, for whatever reason, cemented itself in my memory. He recounts how his father shared a lesson with him regarding the word "Obviously", and it was something along the lines of "If you say it's obvious, but it isn't, then you will offend someone. If it is obvious, then it's superfluous. The word 'obvious' never needs to be used"
I've applied this ever since then and almost never use the word anymore. There are some rare times I find it's useful though, for example if you want to reassure someone that they come across the way they intend to, or in some positive manner: "Obviously you care a lot"
Re: If someone’s having to read your docs, it’s not “simple”
#7This blog is again hard to read.
Re: If someone’s having to read your docs, it’s not “simple”
#8Brought to you by "just simply dot dev"
I believe that is the point?
Re: If someone’s having to read your docs, it’s not “simple”
#9I've had a blog post rolling around in the back of my head for years regarding how "obviously" is the absolute worst word to use in any kind of technical context. And then go through some of the most egregious things labeled as obvious in various peer reviewed research or blog posts.
Re: If someone’s having to read your docs, it’s not “simple”
#10Wow I could not agree with more with you. I think I'm finally improving my writing skills as well !
Also, I find it hilarious that you have an entire website dedicated to make your point. I would give a +2 for that ;)