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 someone’s having to read your docs, it’s not “simple”
51–60 of 146 posts
Re: If someone’s having to read your docs, it’s not “simple”
#5250% 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 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”
#53Re: If someone’s having to read your docs, it’s not “simple”
#54Another 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.
Re: If someone’s having to read your docs, it’s not “simple”
#55This 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.
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”
#56I agree for the most part. However, IMHO using these words (just, simply, etc) occasionally can make the doc more lively and fun to read.
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”
#57Do 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 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”
#58Is 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…
Re: If someone’s having to read your docs, it’s not “simple”
#59 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”
#6050% 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.
They just do stack overflow driven programming, question & paste.