5 ms·

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

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 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?"

segfaultbuserr 5y ago
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.
- bluejellybean 5y ago
  I agree with the "read from the beginning" vs "landed on a page" issue. Linking can solve a lot of these styles of issues, as does keeping in mind the many possible consumers of the given documentation. As a simple example.. 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()).
  - segfaultbuserr 5y ago
    Ha, I edited my comment to say the same thing before I noticed yours. Couldn't agree more.
- jrumbut 5y ago
  I think in the Rails mailer context you're expecting "render a view" to be a comfort zone for the reader, the line is suggesting a mental model you hopefully already have that will really help you understand how the upcoming process will work. "It's kind of like view rendering, so I should expect a template file and the need to correctly set header fields." 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."
atoav 5y ago
I think good documentation would give a bit more orientation on the first sentence. E.g. why not mention what other ways to render a View exist and maybe even link to them "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"
sidlls 5y ago
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.
- mtippett 5y ago
  I actually see just as in a lot of cases as being as a painful indication of a gross trivialization of something. 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.
  - yoz-y 5y ago
    Encountering a “just” triggers my fight or flight response. I often interpret is as something that author has done so many times they have internalised it, regardless of the complexity of the task. It also probably isn’t documented with something more than a deprecated code snippet.
0xEFF 5y ago
It’s really just you. Or it’s just you. Either way, it’s you.
Dylan16807 5y ago
It's just you. Assuming there is a "render a view" mechanism, neither of those statements is clear about whether mailers are a way to use it or an alternative to it. And it's not clear from this text whether there even is a single "render a view" mechanism to begin with! 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.
chrismcb 5y ago
No, the first sentence does not imply that mailers use the same underlying "render a view" mechanism. I would argue it implies the exact opposite, in the mailers are just another way to render the view. The two sentences mean the same thing.
resonious 5y ago
To me, both sentences make it seem like I really want to render a view, and Mailers are one possible way. 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.
pwdisswordfish8 5y ago
> Does this change destroy the meaning of the sentence? Edited that for you.
djur 5y ago
The context of this is the Action Mailer Guide: https://guides.rubyonrails.org/v4.2.0/action_mailer_basics.html 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.)

segfaultbuserr 5y ago

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.

bluejellybean 5y ago
I agree with the "read from the beginning" vs "landed on a page" issue. Linking can solve a lot of these styles of issues, as does keeping in mind the many possible consumers of the given documentation. As a simple example.. 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()).
- segfaultbuserr 5y ago
  Ha, I edited my comment to say the same thing before I noticed yours. Couldn't agree more.
jrumbut 5y ago
I think in the Rails mailer context you're expecting "render a view" to be a comfort zone for the reader, the line is suggesting a mental model you hopefully already have that will really help you understand how the upcoming process will work. "It's kind of like view rendering, so I should expect a template file and the need to correctly set header fields." 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."

atoav 5y ago

I think good documentation would give a bit more orientation on the first sentence. E.g. why not mention what other ways to render a View exist and maybe even link to them "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"

sidlls 5y ago

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.

mtippett 5y ago
I actually see just as in a lot of cases as being as a painful indication of a gross trivialization of something. 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.
- yoz-y 5y ago
  Encountering a “just” triggers my fight or flight response. I often interpret is as something that author has done so many times they have internalised it, regardless of the complexity of the task. It also probably isn’t documented with something more than a deprecated code snippet.

0xEFF 5y ago

It’s really just you. Or it’s just you. Either way, it’s you.

Dylan16807 5y ago

It's just you. Assuming there is a "render a view" mechanism, neither of those statements is clear about whether mailers are a way to use it or an alternative to it. And it's not clear from this text whether there even is a single "render a view" mechanism to begin with! 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.

chrismcb 5y ago

No, the first sentence does not imply that mailers use the same underlying "render a view" mechanism. I would argue it implies the exact opposite, in the mailers are just another way to render the view. The two sentences mean the same thing.

resonious 5y ago

To me, both sentences make it seem like I really want to render a view, and Mailers are one possible way. 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.

pwdisswordfish8 5y ago

> Does this change destroy the meaning of the sentence? Edited that for you.

djur 5y ago

The context of this is the Action Mailer Guide: https://guides.rubyonrails.org/v4.2.0/action_mailer_basics.html 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.)