Arbital "requires" relationship

When a page has been writ­ten with some as­sump­tions about what the user knows, these as­sump­tions are de­clared ex­plic­itly as re­quire­ments. This way the reader is aware that they might not un­der­stand the page fully, be­cause they might be miss­ing some req­ui­sites. (Of course, they are still wel­come to read ahead if they choose to.) For ex­am­ple, a page teach­ing “Mul­ti­pli­ca­tion” will have “Ad­di­tion” as a re­quire­ment. The re­quire­ment is it­self a page, in this case about ad­di­tion.

When to add a requirement

Add a re­quire­ment when you are pretty sure the reader will not un­der­stand the page with­out this prior knowl­edge. For ex­am­ple:

  • If you read a tech­ni­cal dou­ble blind study re­sults, and they don’t make a lot of sense to you un­til you look up all the rele­vant statis­tic terms, then you should add “Statis­tics” as a re­quire­ment.

  • If you find an in­ter­est­ing bak­ing recipe, but it’s very sparse on in­struc­tions, then it’s prob­a­bly as­sum­ing you have sig­nifi­cant ex­pe­rience with bak­ing and can come up with your own in­struc­tions. You should add “Ad­vanced bak­ing” as a re­quire­ment.

If you are writ­ing a new page, you can add re­quire­ments as a way to sim­plify your task as a writer. You can as­sume that the read­ers will come in with the prior knowl­edge, and you in­di­cate that as­sump­tion by adding the nec­es­sary re­quire­ments. For ex­am­ple:

  • While writ­ing ad­vanced tips on play­ing poker you can as­sume that the reader already knows the rules of poker and ba­sic strat­egy by spec­i­fy­ing “Poker rules” and “Ba­sic poker strat­egy” as re­quire­ments.

  • Writ­ing a page about di­rec­tives in An­gu­larJS will be eas­ier if you as­sume that the reader already knows “JavaScript” and “An­gu­larJS ba­sics”.

It’s okay for a page to re­quire it­self. This of­ten hap­pens when it’s writ­ten as a refer­ence, i.e. it as­sumes that the user already knows the topic, but needs to look up some par­tic­u­lar part that they for­got.

When not to add a requirement

  • Don’t add a re­quire­ment just be­cause the page is talk­ing about that topic. Use tags for that. For ex­am­ple, read­ers can en­joy Money­ball with­out know­ing any­thing about Oak­land Ath­let­ics or even base­ball, for that mat­ter.

What’s the differ­ence be­tween a re­quire­ment and a par­ent?

Par­ent re­la­tion­ship is more di­rect. It im­plies that the pages can’t re­ally be sep­a­rated; the child is a crit­i­cal com­po­nent of the par­ent. E.g. a chap­ter is a child of the book, a re­search pa­per is a child of the jour­nal(s) it’s pub­lished in, page about Ad­di­tion is a child of Arith­metic. The child page is always within the same gen­eral topic as the par­ent page.

On the other hand, re­quire­ment re­la­tion­ships can span many differ­ent top­ics. Many pages out­side of math have some math as a re­quire­ment. Usu­ally, it’s also pos­si­ble to rewrite the page in such a way as to not need the re­quire­ment or to need an­other set of re­quire­ments, i.e. re­quire­ments are mod­u­lar.

Some­times it can be un­clear if the pages should have a re­quire­ment re­la­tion­ship. If you run into a case you can’t clearly re­solve, please post it here, so we can dis­cuss it, learn from it, and re­fine these defi­ni­tions.