Hacker News new | ask | show | jobs
by mjw1007 1453 days ago
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.