Flyers first pass check

[IJW-Wartrader]

I'm about to start checking through the Flyers section, and have a few requests:

• All the missions contain an identical 'Declare the mission' section. Can I move this to flyer-missions.adoc?
• You've put the missions in alphabetical order, but this means that the Air Transport mission refers to the Ground Attack mission which comes afterwards. Can I change the order of the missions back to the original Ground Attack/Air Transport/Intercept sequence?

[digi-brain]

This got longer than I'd intended, as these things tend to do! XD Ah well, it is as useful for me to practice articulation of these things is it is to give an explanation of my thinking for your benefit.

As always, assuming I'm not missing some nuance in what you're asking:

---

• All the missions contain an identical 'Declare the mission' section. Can I move this to flyer-missions.adoc?

I'd be against this. In modern topic-based writing we try to avoid reliance on the hierarchical context that the topic is in to complete the gap in information. The topic may be reused in another context that lacks that information, or given modern search and reader habits, readers may land on the topic first and never look at the parent topic anyway.

Thus, it is much better that each mission topic is 'complete' in terms of the logical flow that it describes.

• They are pretty much 'task' topics, with prerequisites and procedural steps — it's a bit daft to put part of this information somewhere else and thus make task topics 'incomplete' when you can put the info right there at the point of use.
• It's needless to consolidate such a small snippet of task-based info into the parent 'organisational' topic just because they all have it in common — in such scenarios, rather than force the reader to rely on their wider knowledge and memory it is much better to reuse and repeat snippets of content at the point of use.
• The section in the Intercept mission isn't identical to the others — it has an additional sentence.

---

• You've put the missions in alphabetical order, but this means that the Air Transport mission refers to the Ground Attack mission which comes afterwards. Can I change the order of the missions back to the original Ground Attack/Air Transport/Intercept sequence?

You could, but there's really nothing to gain from it. Similar to the above, when a topic is 'complete' then you don't have to rely on the user to read topics in a particular order to understand and use them. We shouldn't need 'progressive disclosure' in this case and it is bad practice to rely on a specific linear order of reading (except in a defined procedure/sequence, of course).

This topic does still refer to the Ground Attack topic — but only in passing for comparative purposes. The reader isn't actually reliant on that other topic as a foundation before they can use this topic.

The better solution is if we tweak that bit of text to be a tip, and insert new introductory fluff above it. Arguably, the Ground Attack topic might benefit from a similar tip to draw comparison in the opposite direction — or there should be one tip to compare the two, that we repeat in both places.

[IJW-Wartrader]

I'd be against this. In modern topic-based writing we try to avoid reliance on the hierarchical context that the topic is in to complete the gap in information. The topic may be reused in another context that lacks that information, or given modern search and reader habits, readers may land on the topic first and never look at the parent topic anyway.

OK, but from the point of view of a reader, I expected to find information about declaring missions in the Flyer missions page, rather than inside each mission. Partly because it is written as a procedural step, and not as a prerequisite. The duplication of text was a lesser issue than the structure, sorry for not saying that in the original post, as I wrote the post before getting too deep into editing mode.

It's not a big deal, but it definitely jarred my concentration while reading each mission.

---

• The section in the Intercept mission isn't identical to the others — it has an additional sentence.

This is a separate issue that I've flagged in my edit but not committed yet.

You may declare an Intercept mission with any Ready Flyer detachment that you have not already committed to another mission.

I don't understand the purpose of this additional sentence. You could replace 'Intercept' with any of the other missions and it would be equally applicable.

---

• You've put the missions in alphabetical order, but this means that the Air Transport mission refers to the Ground Attack mission which comes afterwards. Can I change the order of the missions back to the original Ground Attack/Air Transport/Intercept sequence?

You could, but there's really nothing to gain from it. Similar to the above, when a topic is 'complete' then you don't have to rely on the user to read topics in a particular order to understand and use them. We shouldn't need 'progressive disclosure' in this case and it is bad practice to rely on a specific linear order of reading (except in a defined procedure/sequence, of course).

For experienced players who are using the site purely as a reference tool to double-check stuff they've read before, I agree completely. But that's only one (very important!) use case.

For players who are learning the game, they're going to be reading sequentially, guided by the strong linearity of an Antora site, with its ordered menu and previous/next links at the bottom of each page. This is how I approached the section on my first read-through, so a comparison to something I hadn't got to yet was distracting.

The better solution is if we tweak that bit of text to be a tip, and insert new introductory fluff above it. Arguably, the Ground Attack topic might benefit from a similar tip to draw comparison in the opposite direction — or there should be one tip to compare the two, that we repeat in both places.

The same note in both places would definitely be an improvement, but I think there's still a strong argument for placing Ground Attack first in the menu (and therefore in Antora's linear structure).

Ground Attack is the 'default' Flyer mission and the most important one to read and understand, as the other missions are variants of it or a response to it. Putting Ground Attack first emphasises this, but makes no difference to players who are going direct to the page. And in a list of three missions (four, if/when we move Evac into the main list) doesn't need to be in alphabetical order to help find specific items.

Listing them in 'Ground Attack/Air Transport/Intercept' order gives us 'standard mission/variant of that mission/response to the first two missions'.

[IJW-Wartrader]

On a separate topic, I'm currently working on revised text for all references to 'hits' on Flyers, as the original GW was horribly ambiguous – as you've found yourself and as I've observed in several discussions in person and online.

I'm probably going to borrow the 'successful hit dice' terminology from the Shooting phase, and reserve 'hit' for successfully making the second Armour roll.

In very rough form, something like this:

1. Make your Snap Fire rolls.
2. Discard dice that scored lower than the lowest Armour value.
3. Allocate successful hit dice.
4. Discard any allocated dice lower that Flyer's Armour.
5. Roll any remaining dice to see if the Flyer is driven off (and temporarily damaged), or if it is hit.

For dogfights it gets simplified to:

1. Make your Gunnery dice rolls against a target.
2. Discard dice that are lower than the target's Armour.
3. Roll any remaining dice to see if the Flyer is driven off (and temporarily damaged), or if it is hit.

[digi-brain]

OK, but from the point of view of a reader, I expected to find information about declaring missions in the Flyer missions page, rather than inside each mission.

Conversely, when I put myself in the shoes of a reader, I'd find it quite irksome not to have the complete information in the mission itself.

You could say something more general in the parent topic about as well I suppose, as part of a general overview of how all missions work. It'd be a bit redundant because really you should still have it in the actual topics for the reasons I mentioned.

Partly because it is written as a procedural step, and not as a prerequisite.

I see the structure of the missions as:

(a) Understand the circumstances that allow you to declare the mission. (Prerequisites)
(b) Understand when exactly you may declare the mission if the circumstances allow. (Doing it, part one)
(c) How to actually carry out the mission. (Doing it, part two)

To my mind it'd be weird to put (b) before (a). Especially when you move (b) up a level to a parent topic that really only exists for organisational purposes — so now you go straight from (a) to (c) and have to remember that (b) is a thing somewhere else.

I see some of what you're saying, and there's always some level of subjectivity — but I think we'll have to agree to disagree on this one. There are also those other 'good practice' reasons I mention, and I'll always lean in favour of those unless there is a good, clear reason to 'break the rule' — which I'm not seeing here as yet.

---

doesn't need to be in alphabetical order to help find specific items

I think that there are valid points on both sides of the argument, but yes, the fact that the list of mission topics is short does mean that a predictable (alphabetical) order doesn't yield any great practical benefit. I'm happy to go along with the change in order back to the original.

[digi-brain]

On a separate topic, I'm currently working on revised text for all references to 'hits' on Flyers, as the original GW was horribly ambiguous – as you've found yourself and as I've observed in several discussions in person and online.

Yes indeed, horribly ambiguous at times. What you suggest sounds good on the whole to me. When we get into the nitty gritty we might debate some specific terminology, but I agree entirely with the overall idea that we should carry through on our efforts to rationalise and disambiguate terminology around 'hits' and fix the issues in the flyers rules.

[IJW-Wartrader]

Partly because it is written as a procedural step, and not as a prerequisite.

I see the structure of the missions as:

(a) Understand the circumstances that allow you to declare the mission. (Prerequisites)
(b) Understand when exactly you may declare the mission if the circumstances allow. (Doing it, part one)
(c) How to actually carry out the mission. (Doing it, part two)

To my mind it'd be weird to put (b) before (a). Especially when you move (b) up a level to a parent topic that really only exists for organisational purposes — so now you go straight from (a) to (c) and have to remember that (b) is a thing somewhere else.

Sorry, my revised point may have been unclear - I'm not bothered about where the text about declaring missions is, and you make very strong points about including the whole text in each mission page. But I think I may have worked out where we are getting some wires crossed. In particular...

(a) Understand the circumstances that allow you to declare the mission. (Prerequisites)

This is not explained anywhere. My default reaction when I see the Requirements section is that I expect a list that I have to fulfil in order to perform the mission, because I already declared the mission back when I was checking readiness states in the Start phase. So I see a list of requirements, and then I see a section about declaring the mission which appears to be out of sequence and written as a task that needs to be done after I've already reached the point of performing the mission.

This is further confused because what you've listed in the Requirements sections aren't prerequisites, but are limitations on how you perform parts of the missions, or descriptions of how the missions interact with other actions or detachments.

In terms of prerequisites for declaring missions, Ground Attack and Intercept have one single prerequisite – the detachment must have its HQ in the Ready state*.

Air Transport has two additional prerequisites:

1. The detachment must have at least one Flyer with Transport (X) that is in Ready state.
2. You must have an off-board non-flyer detachment that is ready to arrive.

*I've already corrected the readiness states file to say that you need the HQ unit in Ready state, rather than a regular Flyer unit.

[IJW-Wartrader]

P.S. I think adding a 'check prerequisites' step to the Flyer missions is a very good idea, but how and when it is checked needs to be spelled out.

[IJW-Wartrader]

So far, I haven't made any major structural changes apart from replacing the 'hit' terminology and changing the order of the three missions.

For the mission pages, we might need a video chat to work out what would work best, or I can restructure one of them as an example for you to look at.

Flyers and Flak – I'm currently planning to rewrite the Flak orders section so that it uses multiple Snap Fire rolls, rather than GW's approach of using completely new text for something that (at the per-die level) is functionally identical to Snap Fire.

[digi-brain]

I started to try to reply to your points, but I think I simply don't see what you're getting at. So yes, I think a video call might be a simpler way to go. Or indeed you could do one to demonstrate and perhaps it'll become clearer. Happy to do either/both as you see fit.

---

As an aside to the main issue, a more general question that this throws up for me:

*I've already corrected the readiness states file to say that you need the HQ unit in Ready state, rather than a regular Flyer unit.

I wonder how meaningful the HQ/command rules are for flyers? I know you have to pay the Detachment HQ cost and they have a chain of command — but what do the HQ rules actually do for flyers, aside from implying a limit to how far you can spread them out for their attack run? If the HQ specifically must be Ready before you can declare a mission, doesn't that make flyers even more crap in this edition? The entire rest of the detachment could be Ready but you're stuck for another turn because the HQ is in the Rearm state?

---

Flyers and Flak – I'm currently planning to rewrite the Flak orders section so that it uses multiple Snap Fire rolls, rather than GW's approach of using completely new text for something that (at the per-die level) is functionally identical to Snap Fire.

I don't see exactly what you mean, but I think I get the general idea. Even after I'd reworked the original text, it still felt clumsy somehow. If you have a way to rework the rules to something functionally equivalent but simpler or more consistent then that seems like a good thing!

[IJW-Wartrader]

Doh, I thought I'd posted this reply, but apparently not...

As an aside to the main issue, a more general question that this throws up for me:

*I've already corrected the readiness states file to say that you need the HQ unit in Ready state, rather than a regular Flyer unit.

I wonder how meaningful the HQ/command rules are for flyers? I know you have to pay the Detachment HQ cost and they have a chain of command — but what do the HQ rules actually do for flyers, aside from implying a limit to how far you can spread them out for their attack run? If the HQ specifically must be Ready before you can declare a mission, doesn't that make flyers even more crap in this edition? The entire rest of the detachment could be Ready but you're stuck for another turn because the HQ is in the Rearm state?

As best as I can parse the Q&A for Flyer detachments that have got split, yes.

Q: When members of a flyer detachment become damaged, that detachment has two elements that finish rearming/refueling on differing turns. Which element(s) of this flyer detachment may fly missions, and when may they fly them?

a. Both elements of the detachment may fly missions whenever they become rearmed and refueled. The element of the detachment that does not include an HQ should select one flyer to act as its HQ.
b. Both elements. It is not necessary to choose an interim HQ for element that does not have one.
c. Only the element of the detachment which includes the HQ may fly missions when rearmed and refueled. When the other element is rearmed/refueled, it must still wait to join its brethren with the HQ.
d. Only the bigger element of the detachment may fly independent missions, regardless of which element the HQ is in.
Neither element may fly a mission until the other is also rearmed and refuelled.

A: A flyer that is damaged can't fly missions on its own (unless it is all that remains of the detachment, of course!). If the rest of the detachment flies a mission while the damaged flyer is being refueled, it simply remains for an extra turn at the refueling stage in order to catch up with them.

From https://thehobby.zone/resources/e40k-compendium/Content/More/QuestionsAndAnswers/QA_Flyers.htm

---

Flyers and Flak – I'm currently planning to rewrite the Flak orders section so that it uses multiple Snap Fire rolls, rather than GW's approach of using completely new text for something that (at the per-die level) is functionally identical to Snap Fire.

I don't see exactly what you mean, but I think I get the general idea. Even after I'd reworked the original text, it still felt clumsy somehow. If you have a way to rework the rules to something functionally equivalent but simpler or more consistent then that seems like a good thing!

Roughly speaking:
Flak units get to Snap fire at full Range against Flyers and Drop Pods.
Flak units on Flak orders get a pool of Snap Fire shots to use this way, and can choose how many shots to use at once.

But I'll see how messy it gets as actual written rules...

[IJW-Wartrader]

I've committed the changes so far, including the Flak rewrite. You can have a look now if you want, or wait until I've rewritten one of the missions, and then I'll start a pull request.

[IJW-Wartrader]

Pull request is up: #33