Live data from Hacker News

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

justsimply.dev

51–60 of 146 posts

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

#51
post #39

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 i…

If you think writing down some good examples and explaining them takes "an hour", you have never written documentation. Writing good documentation takes forever!

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

#52

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.

A company that provides documentation that is complete and easy to use is a good company.

A company selling a product that requires the customer to search third party documentation for usage is a bad company.

For software tools, an educated customer is going to choose companies that have products that help solve their problems, not ones that add to them (in the form of more work to seek out out-of-band documentation).

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

#54
post #2

Another thing you should not do is name things “fast”. It will end up not being fast (esp when you find the next faster thing) or else someone will find security holes in it.

So far, Fast Fourier Transform and Quicksort still holds up well (there are faster algorithms, but both remain adequate choices for general use). But I do agree with you, they're exceptions rather than the rule, e.g. Fast Ethernet, only 100 Mbps ;-)

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

#55

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.

Serverless claims to be simple. But they don’t add “if you are building a toy project”. Therefore, it would be better if they just didn’t say it was simple at all.

They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.

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

#56

I agree for the most part. However, IMHO using these words (just, simply, etc) occasionally can make the doc more lively and fun to read.

Do you have an example of such writing? Or produce an example?

I'm having a hard time understanding how such language would make documentation more "lively and fun to read".

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

#57

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 don't actually think I've ever seen that kind of language in technical docs.

I agree I don't see that in Big Vendor Co. product documentation where Procurement cut a 5+ USD figure check to license it per year (or equivalent subscription).

In internal documentation within a company, I see that kind of language all the time. Yet it is the internal documentation that so many of my clients' staff rely upon in their daily operational activities, so while the page count of the internal documentation doesn't match the vendor documentation, the use of that language there hurts my clients a lot more.

This leads to a lot of the tribal knowledge-oriented activities I see in most of my clients. The documentation is so disjointed because no one in leadership comprehends how much productivity is lost (because the tribal knowledge papers over the functional loss with unperceived efficiency loss by forcing tightly coupled organizational inter-relationships, reducing organizational agility and capacity to handle complexity) when the documentation provides no pointers between the interstices of detail and scope, or hopelessly mix up the context.

It is more of a mixed bag in smaller vendors' software and open source though in aggregate better than internal documentation, and the more successful Big Cloud vendors tend to be relatively better at this. But still far from Apple Macintosh programmer documentation after they opened it up more, IBM mainframe, some sets of inter-related US military field manuals.

The most pernicious trend I've seen lately is a level of technical writing that can only be charitably called "symbol manipulation by non-domain familiar writers" who plug and play edits of successive versions of documentation that have been outsourced/offshored to writers incentivized by number of documentation incidents closed than actual coherency across not just the paragraph, but across the page, sections, chapters and books. English as a second language isn't their challenge; within the scope of their limited edits, it is perfectly acceptable; misaligned incentives (often arising from mis-scoped requirements) is the problem.

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

#58

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…

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

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

#59
Is this accurate?

  This library] makes it painless to [do difficult thing].
  [Complicated thing] made simple and easy.
  All you have to do is just [difficult thing].
Third line should read "All you have to do is [many, often comprehensible steps] using our API to do [difficult thing]." which, in my experience, is enough to get me in a spot where I can do enough and/or read the source code to figure out how certain edge cases are handled.

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

#60

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.

Not sure about the percentage but plenty are from people that don't even bother to read what is available or buy a book!

They just do stack overflow driven programming, question & paste.

Post reply on HN