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

121–130 of 146 posts

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

#121

Post by pronik »

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've used a lot of systems/libraries/etc. which claim to be "simple", but are really anything but. In many cases, "simple" equals to "primitive", which means that as soon as I move beyond the five-line example from the README I'm very likely to stumble upon a problem which will easily take a couple of days of furious googling, code-reading and issue-creating to get around.

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

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

#122

Post by doublerabbit »

dariusj18 wrote: post #120
TeMPOraL wrote: post #100

Earlier quoted context omitted.

The same thing you do with your Word documents. NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.

LatestNewCountdown2Final.docx

FinalLatestNewCountdown2v3.docx

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

#124

Post by smasher164 »

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.

Same. I'm often surprised as to how far programmers will go to disparage the quality of docs, as opposed to just reading them. Like I get that there are factors affecting their accessibility, e.g. internationalization, but it is your literal job to read this information.

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?

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

#125

Post by pwdisswordfish8 »

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…

> Does this change destroy the meaning of the sentence?

Edited that for you.

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

#126

Post by MattGaiser »

aspaviento wrote: post #82
MattGaiser wrote: post #44

Earlier quoted context omitted.

The problem with many more niche things is that it hasn't gotten to the point where decent answers have accumulated on Google. 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.

OfficeJS Add-In or the old one?

The new OfficeJS one. Try running the Angular tutorial in a desktop version of Word, which uses Legacy Edge/IE 11 as its runtime or at least did when we were doing this. It won't work.

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

#127

Post by kossTKR »

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…

Exactly. Examples always trumps some convoluted explanation.

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.

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

#128

Post by KptMarchewa »

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…

That's just lazy javadoc style. The worst kind of documentation, since it adds nothing over looking at code itself.

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

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

#129

Post by lovegoblin »

thiht wrote: post #89
bob_roberts wrote: post #84

Earlier quoted context omitted.

Technical writer here. I avoid saying something is "simple," because whether it's simple is subjective and is relative to the reader's background knowledge. So at best it's unhelpful, and at worst it can be insulting. 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.

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

Post reply on HN