News for hackers. Stuff that matters.
Re:The Surprising Power of Documentation by crispyambulance on Monday June 12, 2023 @09:14AM (#36292895)
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.
Re:The Surprising Power of Documentation by muser8 on Monday June 12, 2023 @09:54AM (#36293448)
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.

Re:The Surprising Power of Documentation by SkipperCat on Monday June 12, 2023 @10:12PM (#36304258)
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.