Hacker News new | past | comments | ask | show | jobs | submit login

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.




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


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()).


Ha, I edited my comment to say the same thing before I noticed yours. Couldn't agree more.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: