Brought to you by "just simply dot dev"
I believe that is the point?
Yeah, sorry, I wasn't being sarcastically ironic or anything.
If someone’s having to read your docs, it’s not “simple”
21–30 of 146 posts
Re: If someone’s having to read your docs, it’s not “simple”
#22This seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library author says “makes X simple” they mean relative to existing ways of doing X. They don’t literally mean simple in absolute terms. The statement is useful because it immediately conveys the goal of the library.
It is bad writing style as well. Streamlining the narrative in your tutorial and avoiding unnecessary words decreases the mental load of the reader.
Re: If someone’s having to read your docs, it’s not “simple”
#23This seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library author says “makes X simple” they mean relative to existing ways of doing X. They don’t literally mean simple in absolute terms. The statement is useful because it immediately conveys the goal of the library.
Personally, I don't find it insulting, but it does sometimes in a bad day help kick-starting the classic imposter syndrome of "I don't get it, oh no, I'm a fraud..."
Re: If someone’s having to read your docs, it’s not “simple”
#24Do not use adverbs in technical writing period
Yeah - I don't actually think I've ever seen that kind of language in technical docs. I don't think this problem exists. Maybe for some very experienced juniors... but you'd hope they'd get that silliness slapped out of them by more experienced colleagues rather quickly
Re: If someone’s having to read your docs, it’s not “simple”
#25Or worse yet, docs that aren't written by a human, but extracted out of comment-less source code.
There is a tendency to actually document the first point of contact with code, but nothing after that.
Re: If someone’s having to read your docs, it’s not “simple”
#26I'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.
Me: new (to me) high school, 1978. In the headmaster’s western civ class. In the first test (three questions, answer one, use as many blue books as you need) I wrote, “Obviously...”.
When the results were handed back I looked at my book. Where I had written, “obviously” he had crossed out that word and a lot of subsequent text. He wrote, “since it was obvious I didn’t bother to read it.” Forty odd years later I have never forgotten the lesson which affected me not simply in regards to the word “obviously”.
(The whole class failed that test and there followed quite a bit of instruction on how to to do schoolwork. I now wonder if it even counted against our grade?)
Re: If someone’s having to read your docs, it’s not “simple”
#27This seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library author says “makes X simple” they mean relative to existing ways of doing X. They don’t literally mean simple in absolute terms. The statement is useful because it immediately conveys the goal of the library.
Right, except if the project didn't actually make the actual thing you want to get done Y (for which you were using X) simpler, but made it harder, because the docs for the new tool are nonexistent/obvious setup for the language/platform/framework produces an error, etc.
No one is complaining about projects that say they're simple if they actually are simple and easy to use (i.e. download a binary, run the binary, it doesn't break and does the ~right thing). I think this is more a reaction to when people say "oh it's simple just and you're done!", or even worse when they say "oh it's simple just download and run" and when you do that you're hit with an incomprehensible error/notation talking about deep internals you have to configure.
Re: If someone’s having to read your docs, it’s not “simple”
#28Is it just me, or does this change in particular totally destroy the meaning of the sentence?
Original:
> Mailers are really just another way to render a view.
"Edited":
> Mailers are another way to render a view.
The original sentence suggests that, while mailers may look different, they use the same underlying "render a view" mechanism (as some other part of Rails, presumably). The revised version makes it sound like if I wanted to render a view, I could choose to use either a mailer or some other system to accomplish that task. Like, "hmm, I really want to render this view, should I use a templating system or a mailer?"
Re: If someone’s having to read your docs, it’s not “simple”
#29This seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library author says “makes X simple” they mean relative to existing ways of doing X. They don’t literally mean simple in absolute terms. The statement is useful because it immediately conveys the goal of the library.
The problem for me is that it over-estimates my competence. I often have no idea how to do simple thing X as required, so would appreciate a tutorial link or a more full explanation.
Re: If someone’s having to read your docs, it’s not “simple”
#30Is it just me, or does this change in particular totally destroy the meaning of the sentence? Original: > Mailers are really just another way to render a view. "Edited": > Mailers are another way to render a view. The original sentence suggests that, while mailers may look different, they use the same underlying "render a view" mechanism (as some other part of Rails, presumably). The revised version makes it sound li…
I agree. The original sentence probably makes sense in context for a reader who read the docs from the beginning. I didn't read it, but I assume the author already introduced similar ways to "render a view", so saying "really just another way" implies the new one isn't fundamentally different and not all that important. On the other hand, it can sound annoying for a reader who landed to this page from a search engine. I think it shows the somewhat inevitable tension between documentation as a standlone work and documentation as a random-access reference.
Nevertheless, as the author said, I do find removing the superfluous "just" after the first sentence is warranted. The original text used 3 "just". One "just" in the first sentence is enough. And definitely don't write "painfully simple".
---
On second thought, if this is what you want to express by using a "just", a better idea is to say it explicitly, let me try...
> Mailers is yet another option to render a view. similar to the HTTP module. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead.
This can be the better alternative of both versions. Be straightforward, don't use subtle language in a technical document.