Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

If someone’s having to read your docs, it’s not “simple”

justsimply.dev

Post reply on HN
Print view View original

131–140 of 146 posts

Re: If someone’s having to read your docs, it’s not “simple”

#131

Post by djur »

csande17 wrote: post #28

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 context of this is the Action Mailer Guide:

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

Re: If someone’s having to read your docs, it’s not “simple”

#132

Post by Kronen »

sumtechguy wrote: post #115
pistoriusp wrote: post #67

As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.

I just wish many of the docs were better. 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' checkma…

There is a difference between documentation and tutorials.

Re: If someone’s having to read your docs, it’s not “simple”

#133

Post by djur »

I agree with the removal of "simply" in most cases, as well as useless flourishes like "painfully simple", but I think the example includes a case that isn't meant to be a rhetorical assertion of simplicity:

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

Re: If someone’s having to read your docs, it’s not “simple”

#134

Post by Kronen »

This post is stupid and it's not the first time I've read something like this.

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.

Re: If someone’s having to read your docs, it’s not “simple”

#135

Post by thiht »

lovegoblin wrote: post #129
thiht wrote: post #89

Earlier quoted context omitted.

Simple is the opposite of complex, not the opposite of hard. Saying something is simple has meaning, and it's not insulting.

> Simple is ... not the opposite of hard. ...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

When we say "simple", we use it as a way to say "not complex". If we want to say "not hard", we say "easy".

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.

Re: If someone’s having to read your docs, it’s not “simple”

#136

Post by Kronen »

Dashron wrote: post #106
thiht wrote: post #89

Earlier quoted context omitted.

Simple is the opposite of complex, not the opposite of hard. Saying something is simple has meaning, and it's not insulting.

It's not a good feeling when you find something "simple" to be hard. Few tasks are easy when you're a new programmer still wrapping your head around conditionals. If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.

The real question and a better post than the original post would be: Are people living in the 21st Century too easily offended?

But it's a rhetorical question...

Re: If someone’s having to read your docs, it’s not “simple”

#138

Post by sumtechguy »

Kronen wrote: post #132
sumtechguy wrote: post #115

Earlier quoted context omitted.

I just wish many of the docs were better. 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' checkma…

There is a difference between documentation and tutorials.

Very much so. But many times just a small example putting the thing in context of usage helps a lot. Sometimes that is needed sometimes it is not. This style is especially useful if you have a call/anticall style like malloc and free. An example of malloc could also have an example of free along with it indicating to the reader (hey you want this too). Some docs it is not obvious what the matching call is.

Re: If someone’s having to read your docs, it’s not “simple”

#139

Post by bnajdecki »

alephnan wrote: post #123

I've found it less complex to just read GCP's SDKs and API libraries source code than to read the documentation.

That's also the approach that we took in the GenDocu project - instead of writing the whole essay, you just generate code sample and the short descriptive comment. Less writing for developers, less reading for consumers.
Post reply on HN