I think the biggest weakness with the four-document model is that it doesn't have a proper place for rigorous documentation of the system's concepts and model.
The biggest problem I find with software documentation is that the only rigorous part is a "Reference" which is organised as a list of functions or configuration options or commands or whatever, and while each individual item looks OK, they don't add up to a full description.
One clue that you've got this problem is having reference items which use technical terms which aren't defined, or are only defined in the informal part of the documentation.
Another form of this problem is a reference that's heavy on how options modify behaviour but omits any promises about the parts of the behaviour which are unconfigurable.
The four-document model's division of "Explanation" and "Reference" doesn't help avoid this problem. The "Explanation" is for teaching and is apparently not intended to be rigorous, and it doesn't tell you to make the "Reference" more than lists of individual items.
Our “Reference” part starts with a “Concepts” before diving into details like the JS SDK, REST API etc. To me, concepts are just reference too, simply on a higher level of abstraction.
The biggest problem I find with software documentation is that the only rigorous part is a "Reference" which is organised as a list of functions or configuration options or commands or whatever, and while each individual item looks OK, they don't add up to a full description.
One clue that you've got this problem is having reference items which use technical terms which aren't defined, or are only defined in the informal part of the documentation.
Another form of this problem is a reference that's heavy on how options modify behaviour but omits any promises about the parts of the behaviour which are unconfigurable.
The four-document model's division of "Explanation" and "Reference" doesn't help avoid this problem. The "Explanation" is for teaching and is apparently not intended to be rigorous, and it doesn't tell you to make the "Reference" more than lists of individual items.