Re:Unified theory of documentation systems
by mjw1007 on Saturday June 25, 2022 @02:20PM
(#31877477)
This variant seems worse than the dataxis one.
It's already a weakness of this "theory" that it leaves only the reference for documentation that's intended to be complete and correct, while also recommending that the reference be organised as a list of the available operations.
But this divio variant goes so far as to say that, when writing the reference, "don't allow explanations of concepts".
I believe good documentation often needs rigorous definitions of the concepts involved, not just a list of functions or configuration items or whatever.
So either the reference should have space for those, or the explanation should be in a more rigorous style, not a "more relaxed" discussion.
It's already a weakness of this "theory" that it leaves only the reference for documentation that's intended to be complete and correct, while also recommending that the reference be organised as a list of the available operations.
But this divio variant goes so far as to say that, when writing the reference, "don't allow explanations of concepts".
I believe good documentation often needs rigorous definitions of the concepts involved, not just a list of functions or configuration items or whatever.
So either the reference should have space for those, or the explanation should be in a more rigorous style, not a "more relaxed" discussion.