3 ms·

The thing is, documentation isn't a monolithic thing --- it really needs to be sub-divided/categorized into subsets which are useful to specific categories of f

The thing is, documentation isn't a monolithic thing --- it really needs to be sub-divided/categorized into subsets which are useful to specific categories of folks working on, or working with, a project: https://diataxis.fr/ https://diataxis.fr/ (originally developed at: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/) divides into 4 types of documentation: - Tutorials - Explanation - How-to Guides - Reference My own documentation got much better when I broke it up along those lines.

pstuart 10mo ago
Agreed, but IMHO it should be layered so one can enter at the highest conceptual level and drill down and back up so there's a continuous flow of understanding.
- WillAdams 10mo ago
  My experience is that if there's too much documentation for a given representation, a not insignificant number of folks will not read it --- divide and conquer seems to be a workable approach.
  - pstuart 10mo ago
    I agree -- my point was to have the details linked in a drill down manner so that one can skim the high level parts but easily expand upon any topic directly from where it's being referenced.
    - WillAdams 10mo ago
      I would like to see a UI/toolkit which implements that easily and works well.
GarnetFloride 10mo ago
That does make a huge difference, though I have found you also need to divide by the audiences. There are usually two main audiences that need addressing: 1. The new user. They typically know nothing about the product, not even why it exists. The CTO/CIO bought it and now you have to use it. They need lots of hand-holding and needs concrete instruction. Tutorials and explanations are focused on them so they can build accurate mental models of how the software work. 2. The experienced user. They have a pretty good idea of how the product works, but business requirements have changed in some way and know needs to make adjustments to their processes. Or just needs reminders of less used features. Good how-tos and reference material is vital. If you don't take care of these things the customer will abandon your product sooner than later.

pstuart 10mo ago

Agreed, but IMHO it should be layered so one can enter at the highest conceptual level and drill down and back up so there's a continuous flow of understanding.

WillAdams 10mo ago
My experience is that if there's too much documentation for a given representation, a not insignificant number of folks will not read it --- divide and conquer seems to be a workable approach.
- pstuart 10mo ago
  I agree -- my point was to have the details linked in a drill down manner so that one can skim the high level parts but easily expand upon any topic directly from where it's being referenced.
  - WillAdams 10mo ago
    I would like to see a UI/toolkit which implements that easily and works well.

GarnetFloride 10mo ago

That does make a huge difference, though I have found you also need to divide by the audiences. There are usually two main audiences that need addressing: 1. The new user. They typically know nothing about the product, not even why it exists. The CTO/CIO bought it and now you have to use it. They need lots of hand-holding and needs concrete instruction. Tutorials and explanations are focused on them so they can build accurate mental models of how the software work. 2. The experienced user. They have a pretty good idea of how the product works, but business requirements have changed in some way and know needs to make adjustments to their processes. Or just needs reminders of less used features. Good how-tos and reference material is vital. If you don't take care of these things the customer will abandon your product sooner than later.