Arbital "requires" relationship

When a page has been written with some assumptions about what the user knows, these assumptions are declared explicitly as requirements. This way the reader is aware that they might not understand the page fully, because they might be missing some requisites. (Of course, they are still welcome to read ahead if they choose to.) For example, a page teaching “Multiplication” will have “Addition” as a requirement. The requirement is itself a page, in this case about addition.

When to add a requirement

Add a requirement when you are pretty sure the reader will not understand the page without this prior knowledge. For example:

  • If you read a technical double blind study results, and they don’t make a lot of sense to you until you look up all the relevant statistic terms, then you should add “Statistics” as a requirement.

  • If you find an interesting baking recipe, but it’s very sparse on instructions, then it’s probably assuming you have significant experience with baking and can come up with your own instructions. You should add “Advanced baking” as a requirement.

If you are writing a new page, you can add requirements as a way to simplify your task as a writer. You can assume that the readers will come in with the prior knowledge, and you indicate that assumption by adding the necessary requirements. For example:

  • While writing advanced tips on playing poker you can assume that the reader already knows the rules of poker and basic strategy by specifying “Poker rules” and “Basic poker strategy” as requirements.

  • Writing a page about directives in AngularJS will be easier if you assume that the reader already knows “JavaScript” and “AngularJS basics”.

It’s okay for a page to require itself. This often happens when it’s written as a reference, i.e. it assumes that the user already knows the topic, but needs to look up some particular part that they forgot.

When not to add a requirement

  • Don’t add a requirement just because the page is talking about that topic. Use tags for that. For example, readers can enjoy Moneyball without knowing anything about Oakland Athletics or even baseball, for that matter.

What’s the difference between a requirement and a parent?

Parent relationship is more direct. It implies that the pages can’t really be separated; the child is a critical component of the parent. E.g. a chapter is a child of the book, a research paper is a child of the journal(s) it’s published in, page about Addition is a child of Arithmetic. The child page is always within the same general topic as the parent page.

On the other hand, requirement relationships can span many different topics. Many pages outside of math have some math as a requirement. Usually, it’s also possible to rewrite the page in such a way as to not need the requirement or to need another set of requirements, i.e. requirements are modular.

Sometimes it can be unclear if the pages should have a requirement relationship. If you run into a case you can’t clearly resolve, please post it here, so we can discuss it, learn from it, and refine these definitions.