61–70 of 146 posts
Another 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.
For example, class names "MailSender" and then you add "NewMailSender". What do you call it when the "NewMailSender" is old?
Earlier quoted context omitted.
Agreed. Same thing with "Smart".
In my mind, "smart" now means something along the lines of "proprietary non-interoperable blackbox surveillance appliance sending your data to arbitrary cloud endpoints for profiling". I am yet to fit a clever backronym for it.
This 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.
For me, "simply" and "just" are speed bumps in my reading. I notice them because they slow me down and serve no useful purpose in writing.
They should add "frankly" to the list.
Is 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…
The word “just” is superfluous in the sentence, and to the author’s point can easily imply more simplicity in use, concepts, etc. than is warranted. Software documentation should be more like scientific article writing: passive, and having few or no modifiers like “trivial” or “just” or the like.
I regularly call out engineers when they say "just", in a lot of cases when I say - can you explain "just" they go and pull out their collection of familiarity and understanding. To which I usually ask - "How much of your understanding will the reader have?".
When I ask them to remove the just, suddenly a single word becomes a couple of sentences that expand the "just". Magically something trivialized becomes described.
Earlier quoted context omitted.
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.
The problem for me is that it over-estimates my competence. We've been told for years that it's demeaning to do the opposite and underestimate or over-explain, so people may have been erring too far in this direction. We've also seen a lot of "the burden of communication lies on the communicator, not the listener," (quotes indicate paraphrasing) but this may also have led to overcorrection on the part of some listene…
If you always include at least a summary of what the user is expected to know, it lets the user read the documentation nonlinearly without getting completely lost when they hit an unfamiliar concept.
It's such an understated skill.
Or 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.
As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.
Lol, as if that’s an easy or trivial thing…
50% of the questions on Stack Overflow are probably because the documentation was not great in the first place. I am surprised how much configuration/installation time I spend on there.
If Stack Overflow ever changes their model/tries too hard to monetize, the resulting chaos will be bad initially, but will probably spur a shift to better documentation across the board. SO serves as unofficial documentation for a lot of projects and once that crutch is gone, it will force projects to either improve or (more likely) stop letting people file issues (because that's where all the stuff would go). Looks…
On that subject, Stack Overflow was just acquired for $1.8 billion.