News for hackers. Stuff that matters.
Re:Teach, Don't Tell by 7402 on Tuesday September 03, 2013 @01:42PM (#6322393)
"The purpose of technical documentation is ... teach them to be an expert user of it"

But maybe I don't WANT to be an expert user! Maybe I just want to USE the damn thing.

It's frustrating when a tool maker thinks that their tool so important that every user must become an expert on every facet of the tool. How about, "The purpose of technical documentation is to teach the user whatever is necessary and sufficient for their particular needs."

I'm a programmer. A few times a year I need to use Photoshop for something Really Simple. I want documentation that can tell me how to draw a rounded rectangle with a shaded gradient inside it (or whatever) as quickly as possible, and tells me as little as possible about anything that doesn't help do that.

Re:Teach, Don't Tell by solistice on Tuesday September 03, 2013 @02:28PM (#6322731)
Doesn't Stack-anything fill that niche already, along with a multitude of youtube videos and online tutorials that will walk you through the most common use cases, especially for software like photoshop?

In case that's an actual question, make a rectangular selection and check the "rounded corners" box at the top left. Select the gradient tool (You can see it by clicking the little paintbucked on the left toolbar for a while, it looks like a gradient). Klick somewhere and drag with the tool selected. And there's your rounded rectange with a shaded gradient inside.

Re:Teach, Don't Tell by ksmiley on Tuesday September 03, 2013 @03:59PM (#6323361)
> Doesn't Stack-anything fill that niche already?

If you ask, "how do I use [library X] to draw a rounded rectangle?" on Stack Overflow, they will put your question on hold until you show code that demonstrates that you tried. This may be difficult for someone who has only just succeeded in getting the library to compile!

To continue the author's car analogy, Ms. Smith sits in the passenger seat while you try to drive to grandpa's house. When you fail to reach your destination and give up, Ms. Smith will tell you what you did wrong. But only if you made a non-trivial effort. If you ram into the living room while trying to exit the driveway, you'll only get a disapproving glare.