Hacker News Reader

Comment by crispyambulance | Hacker News Reader

I agree with everything you said, especially tailoring documentation for intended purpose.

Except...

  > User docs are simple.

User docs are NOT simple. You have to put yourself into the mind of someone who is going to use your software to solve a problem which they have. That's never easy and it gets really hard, really fast, as the software grows in complexity or as your audience gets wider.

View on HN

I should probably elaborate. When saying simple, I meant don't add content that doesn't relate to what the user needs to use the product. There's nothing worse than having to read a several paragraphs of unrelated content just to get to the nugget of info which tells you how to actually use the product.

If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.

To continue this line of thinking: for documents to be useful in helping a customer solve a problem the documents must answer the question 'why would I want to do X.'

A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product.

Providing accessible conceptual guidance can be very challenging depending on the domain.

Reply on news.ycombinator.com