Structure of Information

[trickeydan]

I'd like to open a discussion around the structure of information in the runbook, particularly surround how we organise information that differs by year.

Currently, documentation from different competition cycles is mixed amongst each other, and this makes looking for specific information quite difficult.

I can see a number of possible solutions to this, but please suggest others.

• Organise by year at the highest level.
  • e.g sr2016/competition/arena, sr2016/competition/arena/tokens
  • Allows for topics to be rearranged per year if necessary.
• Organise by year within categories.
  • e.g competition/sr2016/arena, competition/sr2016/arena/tokens
• Organise by year at the topic level
  • e.g competition/arena/sr2016, competition/arena/sr2016/tokens
  • This is most similar to what we currently have

I think that we will make this valuable information more accessible to volunteers by creating a consistent structure within the runbook.

[RealOrangeOne]

Personally I think any year-specific content should be as deep as possible, yielding the latter of your examples. I suspect (and really want!) there to be very little year-specific content as possible.

Taking the arena construction as an example, I think it would be far more constructive for pages to be documented as competition/arena/scaff, competition/arena/timber, competition/arena/truss etc etc. This way someone doesn't need to do the additional thought process of 'What year did we use the timber arena?'.

This falls over slightly when it comes to documenting process-style documentation, as that can't be documented quite as well. In that case, I think having a root page describe how we currently do things, and child pages (or maybe just subsections depending on how detailed the content is) describing how it was done in previous year.

We don't want to be keeping top-level pages of things which we may need. Personally i'd rather see people use the git history for that, and extract it out only when necessary (This does rely on people knowing how to use git, but the blame interface on GitHub is actually quite nice!

</braindump>

[PeterJCLaw]

I'm broadly in favour of pushing year specific information deeply into the hierarchy, though there are cases where having the year-specific entry as a leaf may not work (the arena is one such example). In those cases, I'd still expect the year specific part to be pretty low in the hierarchy.

Regarding processes: I think it's always going to be a judgement call on how much of an old process we keep around. I think we should always keep the rationale and learnings in the documentation, though the guiding line here should be "is this relevant" to how we do things now.

As an example (though ignoring that this topic might not actually fit into the runbook), I don't think we should keep present here the documentation for the previous generation of kit, however I do think it would be worth both mentioning what it was and the improvements which lead to the current kit. The latter part would likely be recursive -- including a summary of the improvements & rationales from all time, where those remain still relevant.

[WillB97]

Given that the vast majority of the year specific information will be the same or similar (i.e. reusing a previous venue will use the layout and network mostly) so it would be most useful if we could present the different setups used, in the way @RealOrangeOne suggested. Then before presenting the selection have a preface which notes which setup was used on each year.

i.e. A scaff arena was used in SR2013, SR2014 and SR2018. The timber arena was used in SR2015.

Also by differentiating year-specific info low down the hierarchy the information remains grouped by area. This is useful when planning as the previously used options are immediately available when organising a particular element.

[trickeydan]

I think consensus was reached here.