When reading succinct technical documentation, I see how so many times the documentation attempts to cover everything possible. ~

Most developers want guidance instead of exhaustive details. Developers want to know where they should focus their time and where they can afford to skim over the documentation. And they want to know where they should expect to encounter problems and difficulties.

A simple framework to use when producing succinct technical documentation is to divide the documentation into three sections.

Maps: Identify what type of problems this documentation can assist you with

Defaults: Understand what the majority of people will experience and what to do about it.

Exceptions: Identify when to deviate from the default recommendations.

Succinct documentation does an excellent job of providing clarity by eliminating edge cases. The more clearly the user understands the documentation the more useful the documentation will be during the time where the user is experiencing the most confusion.

The danger is the temptation to simplify the information contained within the documentation to such an extent that the user is left with a large amount of missing information and no method for seeking assistance with incomplete information.

What situations have you encountered where the information contained within short technical documentation has been more helpful than official technical documentation? ~

▲

WillAdams 10 hours ago | parent | next [-]

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/

(originally developed at: 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.

▲

GarnetFloride 5 hours ago | parent | next [-]

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 6 hours ago | parent | prev [-]

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 5 hours ago \| parent [-]
		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.

▲

d4mi3n 4 hours ago | parent | prev | next [-]

What you describe sounds a lot like Diátaxis[1], which is a strategy for writing and organizing technical documentation. It categorizes docs into one of four categories: tutorials, explanations, how-tos, and references.

Category is derived from a fairly simple heuristic: whether the content informs action or cognition, and whether the content serves the reader’s application or acquisition of a skill[2]. I’m a fan and it’s simple enough that most anyone can learn it in an afternoon.

1. https://diataxis.fr/

2. https://diataxis.fr/compass/

▲

auggierose 4 hours ago | parent | prev | next [-]

You have an interesting commenting style. ~

Lots of sentences occupying an entire paragraph.

Sometimes ending with "~". Usually (always?) your posts end with a question.

You are clearly using some sort of framework for your posts.

Care to elaborate? ~

▲

shakabrah 4 hours ago | parent | prev [-]

Please take your slop comments elsewhere. We are trying for something different here on HN.