Two terms of mine for learning programming via documentation

A short discussion of two ideas for reading documentation — “Jackpots” and “4-Walled Concepts.”

Just to clear the air my story is members only right now because I’m still ironing out how I feel about these terms but I believe that it may be useful to some in the meantime. I might eventually make it free.

So, what is a “jackpot?”

A jackpot is the final page you reach after clicking a foreign concept in documentation to learn about it where that concept makes sense. A common start or step on the way to a jackpot are 4-walled concepts.

Let’s say “object” is linked in a relatively benign description of how something else works so it requires you to click on “object” to learn about that and then one of its method definitions, and one more linked after that one. Jackpot! Renewed you return and onward you read.

A jackpot isn’t good or bad, in fact it can help you realize the relationships between many concepts at once and represents a developer or community’s ability to make the documentation rely on itself only.

Alright, and a “4-walled concept?”

A 4-walled concept is anything referred to in documentation that struggles to define itself on pages other than its main definition.

These are typically the big ideas in a documentation. Something like objects, or a main method that gets referred to as a common word.

Unlike jackpots a 4-walled concept has a higher chance of indicating poor in-text contextual clues or definitions although it isn’t inherently bad, but important to recognize as a learner.

—

Neither of these terms are critiques to me but understanding their ability to turn up in documentation has helped me digest it more clearly. Most notably I am more prone to spending time reading over linked terms when I’m deep into not understanding a page in hopes I stumble upon a jackpot.