If someone’s having to read your docs, it’s not “simple”
justsimply.dev
justsimply.dev
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?"
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.
Original:
> Mailers are really just another way to render a view.
"Edited":
> Mailers are another way to render a view.
My Edit:
> Mailers are another way to render a view, much like the linkTo(RenderMethod()).
I learn best by analogy, so the first version in the article was very helpful and comforting. The second version makes me, and I think the parent and grandparent, expect that view rendering is more like requisite knowledge than a possibly useful analogy. "Only true experts in how views are rendered need apply, I better study that first."
"Mailer is one of muliple ways to render a view. It translates a view into a text- or HTML-Email.
Other available Renderers are PDFWriter, Printer and CSVWriter"
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.
It needs clear wording, perhaps like "this is a wrapper around" or "this is an alternative to" or "this is one of the" followed by more detail.
Perhaps a more effective edit would just use controllers as an analogy from the beginning instead of focusing on views.
> Mailers are like controllers, but for email instead of HTTP.
Edited that for you.
https://guides.rubyonrails.org/v4.2.0/action_mailer_basics.h...
Looking at this documentation in context, the point it's attempting to make here is that since mailers are rendering a view, the appropriate place to call them is from the controller (as opposed to the model, I suppose). The documentation has already repeatedly made the point that mailers are like controllers, that they render views, etc.:
> Mailers are very similar to Rails controllers. They also have methods called "actions" and use views to structure the content. Where a controller generates content like HTML to send back to the client, a Mailer creates a message to be delivered via email.
So I would argue that both the OP's suggested change and a lot of the ones in this thread aren't quite right. The reader has already been told that mailers render views. The "corrected" version misses this and tosses out the main point while preserving the repetitive throat-clearing. Within the context of a step-by-step guide, meant to be read in order, a better clarification might be something like this:
> Since Mailers are another way to render a view, it makes sense to call them from the controller. In our example, we will call the UserMailer at the time a user is successfully created.
(Whether this is actually good advice is a separate question.)
It's such an understated skill.
Lol, as if that’s an easy or trivial thing…
The person that figures out how to copy and paste code for a REST call in that particular framework will still probably fail if they don't notice that they need to adapt it for the network request caching system and the ORM.
But there is no reason to memorize all that syntax and regurgitate it in the most computationally efficient Big O
I value reading the documentation of libraries that I'm using. I don't memorize it, but casually read over it to understand what's possible.
I do not do this for everything, but if it's a piece of technology that I value, then it's probably a good idea to read the docs so that I'm not faced with "I did not know that it could do that" situation.
The amount of times I've seen developers painfully code around something that was already supported in the library they're using is suprizing.
Back in school I was considered a "leet hacker" who was good at computers. I "cracked" an encrypted Word document when someone forgot the password to it (I Googled how to do it). I built my own PC (I Googled how to do it). I downloaded MP3s before they were everywhere (I Googled how to do it). You get the idea...
Nowadays I get paid to do that stuff, but at home I fix my own car when I can, fix my plumbing when I can, fix and maintain my bicycles, do my own networking etc. How? You guessed it... I DuckDuckGo how to do it.
I can read the manual / docs and I can cast an eye over third party packages to see how it works it astounds me that so few people take these simple steps.
I see this 'style' many times in some docs. A bit of doc that basically describes the name of the function/class. But does not show why and how to use it, how it fits in the API system, and so on.
public void DoesXYZ()
Then many times a description of 'a public method that does XYZ' does not return anything.
It is exceedingly unhelpful but meets the 'it is documented' checkmark.
My next step would be to search for an example usage of that thing (usually landing on something like SO or some random training site). Then what sorts of items might it need to work. Why would I use it over something else? Some OK examples of what is going on goes a long way and what sets the expectation of the original dev on how they were expecting you to use it. So I end up spending some decent amount of time reading the tea leaves and if I am lucky the code itself to decode what is going on.
One feed back I consistently give to all vendors is 'your docs need examples and those examples need to be consistent with each other' If I have to open github and spend a few hours reverse engineering that code, and then also try to learn whatever language you thought was fun to play with 6 years ago, I am not going to be happy.
Good docs are like: "this library make you do things like this, this or this, as easy as [show code snippet 1, 2, 3]".
Also a big list of examples should be way easier to just dump into the docs than writing some absurdist essay about the tech, ie. it's even easier for the maintainers.
I vaguely remember the PHP website doing this with their functions on their website with user comments with examples - another example is Mozillas MDN.
Honestly now thinking about it, "user added examples" should be its own category on sites like Github. Seriously why isn't this a thing?
Dozens of "Here's how i used this library to do this" would be amazing.
At the very least, there should be examples of usage.
I never did PHP, but they have one of the best documentation features: comments. It allows you to recognize if a function is a footgun: https://www.php.net/manual/en/function.utf8-decode.php
Also, when I find a lib, I want to read some user stories, not 20 pages of documentation in yet another doc format. Simple user stories. If you need to do A, here are 3 lines. If you need to do B - here are 5 lines. If your lib lacks these user stories, I will probably skip it. Or if I really need it, I will use StackOverflow to find some use cases so I can relate to and get a better understanding of the lib.
_NOW_ I may read the docs after I have the user stories, so they better have some information how you can customize the 3 and 5 lines of code above.
Meanwhile, for reverse engineers, it's a dream come true to be granted any information whatsoever on the product they're reverse engineering. For some reason, programmers want to operate in the context?
Looks like GitHub is already getting ahead of this with the "Discussions" feature.
On that subject, Stack Overflow was just acquired for $1.8 billion.
For what it's worth, I don't think Prosus will make a mistake in this way -- the fact that they've existed all this time without me (or most people, I think) ever hearing about them means that they are good at what they do. Regardless of what their main goals are, I assume that I'll think it's likely I continue to not hear about them.
or a pain to find when searching online in the first place...
Someone who needs handholding or is unsophisticated is a bad customer.
For developer tools and such, an educated person’s game, the sophisticated players will have better LTV than the unsophisticated ones.
I recently had to build a Word Add-In. Not a lot of those built at the moment. So we were dependent on the documentation, which while reasonably comprehensive, had some frustrating gaps in just getting the tutorial code running that took days to resolve.
A company selling a product that requires the customer to search third party documentation for usage is a bad company.
For software tools, an educated customer is going to choose companies that have products that help solve their problems, not ones that add to them (in the form of more work to seek out out-of-band documentation).
They just do stack overflow driven programming, question & paste.
If it's actually not a simple subject or process, don't shortcut on the documentation.
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.
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 <huge amount of setup> 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.
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 listeners.
It's often impossible to predict what knowledge level and cultural background one's readers will have, so somehow we have to find a middle ground and ask that everyone mutually assume good faith and put in some effort to understand the other party, both when communicating and when reading.
Here is a tutorial I wrote:
https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest...
I tried to just link to anything that might require more info. If you know how to do it, great, don't click the link. Otherwise, what you need is right there.
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.
This way, when someone ignores the section and comes to me in incomprehension of a document they were not expected to understand, I can ask them what was unclear about the "About This Document" section. Although that's probably optimistic about how often people read documentation.
What I hate about this kind of bad documentation is that juat by spending an hour and writing down a few good examples and explaining them you could save hundreds of collective brain hours and maybe even improve adoption of your library if that is a relevant category for your project.
But more often than not you will find auto generated documentation where you see nothing on the first page, nothing explaining what that library can do, can't do, is intended to be used for, is not intended to be used for, some usage example how to get started etc.
Instead you will find a half page in some obscure class documentation that seems to be addressed to the dev themselves instead of to any outside audience.
What I mentioned above doesn't have to take long. You built the library. If you cannot write a simple example of how to use it within 5 minutes you probably should rewrite that library before publishing it. Integrate that example into your tests and now you even know when it will fail.
In such a context, it is reasonable to expect documentation to have a lower and upper bound on detail and scope they cover. It is not reasonable to expect all readers to know how to bridge over out of bounds detail and/or scope if they need to for their particular use case.
Examples of operative phrases to use are "for more detail on..." or "for more information on...", the former letting readers know how to obtain prerequisite knowledge, the latter letting readers know how to obtain out of bounds perspectives. Unfortunately, the art of systems-thinking-grade (wonderful link to Russell Ackoff's article on the front page today) technical writing has greatly atrophied in practically all organizations I have consulted for, and deteriorated to tactical-level documentation that reinforces a downward spiral in systems comprehension capabilities across organizations. This stems largely from a global leadership culture that applies the "simply" or "just" mentality to technical writing (which IMHO really should be called "systems writing" when it reaches a certain complexity to point out what we're really trying to accomplish at that arguably different use case, using technical writing as a tiny subset of its value delivery).
They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.
I'm not sure if this is just a front-end JS thing or if everyone is having this problem, but it seems like the majority of people writing docs aren't doing it to educate their users, they're doing it to proclaim to the world how smart they are with their revolutionary new tool that "makes foo simple" (and by that they mean makes foo easier* by adding complexity), and if the person reading it happens to learn something too that's just a bonus.
*until you colour slightly outside the lines and have to dive into whatever their shit library abstracted away anyway.
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.
If you're stuck on a task, the last thing you want to hear is that it's really simple.
On the other hand, I would write that X is a simpler approach than Y, if I was comparing two possible approaches.
If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.
But it's a rhetorical question...
Feeling offended is a very different emotion than feeling alienated.
...yes it is? The word has multiple meanings.
> free from complexity or difficulty [https://www.merriam-webster.com/dictionary/simple]
> involving minimal difficulty or effort [https://www.merriam-webster.com/thesaurus/simple]
etc
Words should be used carefully or we end up with no word to say what we mean. That's why there's literally no word meaning what we want to say by "literally".
But from context you can determine whether "literally" means "literally" or "figuratively". It's the same with "simple", you should assume it means "simple" and not "easy" in the case of a documentation where words are chosen carefully.
"Just" is a huge red-flag for me, not just in documentation, but also in effort estimation, requirements gathering, etc. It's the ??? between underpants gnomes and profit.
I don't think it's insulting my competence, it's just that "simple" is a sign that the original developer is not aware of the complexity (SNMP, anyone?) and hence it's now a trigger word for "prepare to be miserable for a while". And I don't like to feel miserable while dissecting something someone called "simple".
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?)
And omitting the word "obvious" wouldn't make the statement any less obvious. Wouldn't his explanation demand he cross out any basic true statements, no matter how you worded them?
There are good arguments for avoiding the word "obviously" in many circumstances... but I don't buy that argument.
FFmpeg originally stood for "fast forward" but no longer means anything. They do have this problem where they need to replace older APIs with newer ones - their approach is to give the newer ones names with "2" "3" stuck on the end instead of "fast" "faster" etc.
But there are some problems in there, there's something called "simple IDCT" which I have to admit I never fully understood.
For example, class names "MailSender" and then you add "NewMailSender". What do you call it when the "NewMailSender" is old?
NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.
This library] makes it painless to [do difficult thing].
[Complicated thing] made simple and easy.
All you have to do is just [difficult thing].
Also, I find it hilarious that you have an entire website dedicated to make your point. I would give a +2 for that ;)
There is a tendency to actually document the first point of contact with code, but nothing after that.
Of course it's easier now, layers and layers have been added over the years to make programming easier, simpler and for a wider audience. Almost any library is made to make a programmer's life easier and simpler, if you didn't have that library and had to fight directly with the underlying layer it would be an order of magnitude harder for you to do it.
So of course it's easier, because being easier or simpler doesn't mean anything if you don't take into account what you're comparing it to. In this case with the difficulty of what was there before this particular library was written.
The problem is that 30, 40, 50 years ago most of the programmers were smart people, engineers, the best of the best... Making programming simpler every year and for a wider audience has made people with no patience to want to be programmers, they want it all chewed up and they want it all now, instead of struggling with the code or documentation (if any) themselves, and they want to be programmers in a month.
If this is not the case then it's because "it's really hard", sorry but no, something that takes you less than a couple of years to learn to reach an intermediate level is not hard.
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"
But this almost always needs to be someone I have report with. Without knowing the listener, I can't really judge what they'd know or not. And on the web, it's probably not time-sensitive at all, and it's a lot easier to skim the explanation.
I'm having a hard time understanding how such language would make documentation more "lively and fun to read".
I don't know, I really love when I see someone using painless, easy or trivial, my experience is usually that. I think they are nonnegotiable if you have a clue about what you are dealing with.
"RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation.
It's not a coincidence that code is written in a language, it's because it's meant to be self explanatory.
Documentation is relevant for engineering products, electronics, mechanics, etc, but I think I believe that software doesn't need documentation; only the code is required. Documentation should be written as code samples, and that's it.
I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not. Everyone who works in STEM, or the 25% of the most educated people, should be able to write some python.
Totally agree: that's the other website from us that didn't make it to Hacker News today https://dayofcode.co.uk
The best documentation I've seen is usually relatively easy to grok, includes example code for real-life use cases, and come with simple explanations.
Great point, and I'll add: The examples must cover the 80/20 rule -- 80% of the time, people just need simple examples just to get started.
And the simple thing is important-- the examples must be standalone. I can't remember the number of times I just wanted to try out a new library, but couldnt even get the "hello world" version working, and just quit. It's harder if the library/code is in a language you dont use for your day to day job.
I can't quantify it, but I saw the title and thought, "GOSH yes. I HATE those kinds of docs."
I agree I don't see that in Big Vendor Co. product documentation where Procurement cut a 5+ USD figure check to license it per year (or equivalent subscription).
In internal documentation within a company, I see that kind of language all the time. Yet it is the internal documentation that so many of my clients' staff rely upon in their daily operational activities, so while the page count of the internal documentation doesn't match the vendor documentation, the use of that language there hurts my clients a lot more.
This leads to a lot of the tribal knowledge-oriented activities I see in most of my clients. The documentation is so disjointed because no one in leadership comprehends how much productivity is lost (because the tribal knowledge papers over the functional loss with unperceived efficiency loss by forcing tightly coupled organizational inter-relationships, reducing organizational agility and capacity to handle complexity) when the documentation provides no pointers between the interstices of detail and scope, or hopelessly mix up the context.
It is more of a mixed bag in smaller vendors' software and open source though in aggregate better than internal documentation, and the more successful Big Cloud vendors tend to be relatively better at this. But still far from Apple Macintosh programmer documentation after they opened it up more, IBM mainframe, some sets of inter-related US military field manuals.
The most pernicious trend I've seen lately is a level of technical writing that can only be charitably called "symbol manipulation by non-domain familiar writers" who plug and play edits of successive versions of documentation that have been outsourced/offshored to writers incentivized by number of documentation incidents closed than actual coherency across not just the paragraph, but across the page, sections, chapters and books. English as a second language isn't their challenge; within the scope of their limited edits, it is perfectly acceptable; misaligned incentives (often arising from mis-scoped requirements) is the problem.
… which I have found useful in my writing. Avoid adverbs. Compromise before you get to “Why waste time say lot word when few word do trick”.
> really just another way to render a view
This is using "just" in the sense of asserting similarity, not simplicity. And in the context of the sentence, it's being set up as the basis for an argument: "(because) X is just Y, therefore we should..." The original document is kind of repetitive and "bloggy", with a lot of reiteration of the same ideas in a way that feels like it's meant to fill in space between code examples. But I don't think this technique of just removing particular words makes it any clearer or better.
They should add "frankly" to the list.
To your point - I would argue that passive voice is more appropriate for documentation, and active for tutorials.
Can I achieve what I need just by reading the code? If not, it probably means there is a bunch of arbitrary knowledge in configuration, transpiling, generation, linking, novel concepts or language "magic" that you will need to consult the docs for.
If a codebase is idiomatic to the language its written in you really should be able to figure most things out from reading the code. At the very least my IDE should know how to autocomplete functions in the codebase without generating helper files. The helper file is essentially a list of all the missing information in the codebase that someone has had to figure out how to generate and connect.
And he's also misreading what simple means.