Skip to content

Comment on The Grand Unified Theory of Documentation

Comments

In regards to that four-quadrant infographic - how could Technical Reference fall into the category of "theoretical knowledge?"

I'd think tutorials would fall under theoretical because if it gets too practical, are you not effectively writing a how to guide?

I'm not really sure the four categories fit into that quadrant scheme as well as they'd like.

I'm not sure why this is being downvoted. I'll throw in my two cents (not the OP or anything):

It's not theoretical knowledge in the sense of "theoretical/applied physics", but rather theoretical knowledge because there is an extra step between it and application.

So if I give you a list of functions in a module/class and just tell you what they do, that is more theoretical than a code block that you can cut and paste as running code.

I'm not sure how else you would label this axis, theory/practical seems just fine.

This is a good question.

Practical knowledge is knowing how to do something - tie your shoelaces, instantiate a model class, authenticate to an LDAP server.

Theoretical knowledge is knowing what is the case - that the cross-flow valves must be closed at take-off, that everything in Python is an object, what a Python property decorator does.

Technical reference is theoretical knowledge (that you apply in practice), as is explanation. Tutorials and how-to guide contain practical knowledge.

AboutSource Built by g1lg1l

Hackerly is an independent reader for Hacker News, built on the public HN API. Not affiliated with Y Combinator.