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

101–110 of 146 posts

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

#101

Post by jokoon »

If a library/framework doesn't provide samples/examples, then it's probably not a good library.

"RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation.

It's not a coincidence that code is written in a language, it's because it's meant to be self explanatory.

Documentation is relevant for engineering products, electronics, mechanics, etc, but I think I believe that software doesn't need documentation; only the code is required. Documentation should be written as code samples, and that's it.

I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not. Everyone who works in STEM, or the 25% of the most educated people, should be able to write some python.

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

#102

Post by has_many_books »

jokoon wrote: post #101

If a library/framework doesn't provide samples/examples, then it's probably not a good library. "RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation. It's not a coincidence that code is written in a language , it's because it's meant to be…

> I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not.

Totally agree: that's the other website from us that didn't make it to Hacker News today https://dayofcode.co.uk

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

#103

Post by zhdc1 »

jokoon wrote: post #101

If a library/framework doesn't provide samples/examples, then it's probably not a good library. "RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation. It's not a coincidence that code is written in a language , it's because it's meant to be…

I don't know if it's enough to simply provide example scripts and leave users to their own devices - even well documented code takes a while to understand.

The best documentation I've seen is usually relatively easy to grok, includes example code for real-life use cases, and come with simple explanations.

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

#104

Post by rbg246 »

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.

This is precisely what I have realised is my special skill as well!

I can read the manual / docs and I can cast an eye over third party packages to see how it works it astounds me that so few people take these simple steps.

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

#105

Post by wccrawford »

warent wrote: post #6
itsmemattchung wrote: post #3

Another word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.

Years ago, I read Michael Crichton's autobiography "Travels". In that book there is one particular part that, for whatever reason, cemented itself in my memory. He recounts how his father shared a lesson with him regarding the word "Obviously", and it was something along the lines of "If you say it's obvious, but it isn't, then you will offend someone. If it is obvious, then it's superfluous. The word 'obvious' never…

I use it whenever I feel the need to say or explain something, but I'm 90% sure the listener already knows it. Failing to say could lead to a failure at a critical time, but explaining it like they're a simpleton could lead to them being upset about that. So I soften it with 'obviously'.

But this almost always needs to be someone I have report with. Without knowing the listener, I can't really judge what they'd know or not. And on the web, it's probably not time-sensitive at all, and it's a lot easier to skim the explanation.

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

#106

Post by Dashron »

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.

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.

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

#107

Post by shantnutiwari »

jokoon wrote: post #101

If a library/framework doesn't provide samples/examples, then it's probably not a good library. "RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation. It's not a coincidence that code is written in a language , it's because it's meant to be…

>> If a library/framework doesn't provide samples/examples, then it's probably not a good library

Great point, and I'll add: The examples must cover the 80/20 rule -- 80% of the time, people just need simple examples just to get started.

And the simple thing is important-- the examples must be standalone. I can't remember the number of times I just wanted to try out a new library, but couldnt even get the "hello world" version working, and just quit. It's harder if the library/code is in a language you dont use for your day to day job.

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

#108

Post by Kalium »

nitrogen wrote: post #38
MattGaiser wrote: post #29

Earlier quoted context omitted.

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

I've found myself addressing the issue with a section at the top of documentation about the expected reader. I can get quite explicit about what the reader is expected to know, include links to relevant backgrounders, and warn that any reader who does not meet the requirements may have trouble.

This way, when someone ignores the section and comes to me in incomprehension of a document they were not expected to understand, I can ask them what was unclear about the "About This Document" section. Although that's probably optimistic about how often people read documentation.

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

#109

Post by BigJono »

antonvs wrote: post #73
Aeolun wrote: post #55

Earlier quoted context omitted.

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.

Meh. If someone just blindly believes some marketing blurb and ignore the blitheringly obvious challenges, isn't that at least a little on them?

The problem is that those marketing blurbs are never just on the front page these days, they're all through the documentation too. So I can't really fault people too much for falling for them.

I'm not sure if this is just a front-end JS thing or if everyone is having this problem, but it seems like the majority of people writing docs aren't doing it to educate their users, they're doing it to proclaim to the world how smart they are with their revolutionary new tool that "makes foo simple" (and by that they mean makes foo easier* by adding complexity), and if the person reading it happens to learn something too that's just a bonus.

*until you colour slightly outside the lines and have to dive into whatever their shit library abstracted away anyway.

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

#110

Post by techbio »

handrous wrote: post #17
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.

Something that bugs the hell out of me is any file-location or file-name configuration-by-convention thing where every example doesn't clearly state WTF file it's supposed to go in and link to a full example to provide any necessary context. "Gee, I guess I'll scan the whole page... nope, not anywhere on this page, now I get to click around your docs menu trying to figure out where this goes. Thanks." Half the time I…

Path of foo, scope of bar, baz of baz. Context, it will work for you!
Post reply on HN