3 ms·
I agree with everything you said, especially tailoring documentation for intended purpose. Except... > User docs are simple. User docs are NOT simple. You
by crispyambulance 3y ago
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.
- muser8 3y agoTo 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.
- SkipperCat 3y agoI 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.