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

31–40 of 146 posts

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

#31

Post by Animats »

anm89 wrote: post #9

I've had a blog post rolling around in the back of my head for years regarding how "obviously" is the absolute worst word to use in any kind of technical context. And then go through some of the most egregious things labeled as obvious in various peer reviewed research or blog posts.

"Obvious" in mathematics is seldom defined. It does, though, have a specific meaning. Something is obvious if applying standard solving techniques without planning ahead will work. That is, backtracking will not be necessary. In this sense, symbolic differentiation is obvious, but symbolic integration is not.

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

#34

Post by dataflow »

MattGaiser wrote: post #12

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.

> the documentation was not great in the first place

or a pain to find when searching online in the first place...

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

#35

Post by bluejellybean »

segfaultbuserr wrote: post #30
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…

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

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

#36

Post by NateEag »

BrissyCoder wrote: post #24
JoeyBananas wrote: post #11

Do not use adverbs in technical writing period

Yeah - I don't actually think I've ever seen that kind of language in technical docs. I don't think this problem exists. Maybe for some very experienced juniors... but you'd hope they'd get that silliness slapped out of them by more experienced colleagues rather quickly

I have seen this plenty of times.

I can't quantify it, but I saw the title and thought, "GOSH yes. I HATE those kinds of docs."

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

#37

Post by ehnto »

I have a pretty obvious codesmell test that I apply to software codebases,

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.

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

#38

Post by nitrogen »

MattGaiser wrote: post #29
arduinomancer wrote: post #13

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.

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

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

#39

Post by atoav »

arduinomancer wrote: post #13

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.

I don't care if you call something simple, but I'd rather have you make it simple for me if you call it simple. Calling something simple can be a statement of fact ("objectively this thing is simpler than other comparable things") or it can be wishful thinking ("man this is really hard, better give them the motivation to wrap their head around it by taking away the edge"). The latter is what people tend to hate. It is "draw a circle, now draw the rest of the owl"-territory.

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.

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

#40

Post by an_opabinia »

MattGaiser wrote: post #12

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.

Someone who solves problems by Googling is a good customer.

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.

Post reply on HN