Close crop of Angular Fractal Tree. Ink on paper drawing of an angular tree-like diagram branching out from a central circle. Own work. 2020.

Undocumented killer feature

Weirdly incomplete Boeing 737 MAX manuals

by AK Krajewska

On January 5, 2024 the door plug of a Boeing 737 MAX 9 airplane blew out during flight. Nobody died. The flight crew got the plane back down and made an emergency landing. The cabin crew kept the passengers relatively calm. That's the gist of it. In all the discussion that's followed a little tidbit caught my attention:

"No one amongst the flight crew knew that the cockpit door was designed to open in case of a rapid decompression, Boeing is going to make changes to the manuals." The Aviation Herald via Charlie Stross on Mastodon

Now that's interesting. No one knew the door was designed to do that[1]. Boeing will update the manuals [2]. 737 Max, haven't I heard that name before and didn't that also turn out to have involved manuals? Yes, and how!

In 2018 a Boeing 737 MAX 8 airliner crashed killing all passengers and crew. An undocumented feature, the MCAS flight-control system, malfunctioned. The pilots couldn't figure out how to correct the malfunction, because they didn't even know the feature existed. I'm skipping over a lot of stuff here, a lot of painful background and coverups and stuff because I just want to focus on one tiny bit of the story:

"The New York Times reported that before the first 737 Max crashed, the pilot handed control over to the co-pilot. He then spent his final minutes, before he began to pray for his life, paging through the pilot manual, trying to determine what was going wrong. This was futile; any mention of MCAS had been removed." There Are No Accidents: The Deadly Rise of Injury and Disaster—Who Profits and Who Pays the Price by Jessie Singer, 2023 via Shauna GM on Mastodon

Excluding mention of the MCAS flight-control system was not an oversight. It was not a technical writing oopsie. It was a deliberate decision by Boeing, approved by the FAA. When the crashes were investigated and pilots found out about the omission, they were understandably furious.

One of the things the FAA required to certify the 737 MAX 8 airworthy again was an update to the manual.

Danger Warning Caution Notice

When I started pulling together the research for this post, I thought I could write something with a bit of dry humour about the different stakes when you're writing technical documentation for software as a service products, like I mostly do, and when you're writing for aircraft. Like I have a cute speech I give people about the Danger > Warning > Caution > Notice hierarchy in software tech docs and how no one's going to die even if they have catastrophic data loss so let's never ever use Danger. And I thought maybe something here I could dig into with the fact that MCAS was a piece of software and perhaps the less stringent standards of software documentation affected how it was documented. Only no, that's not what happened. Based on everything I read, MCAS had at first been included in the manual and then deliberately removed.

The more I read about the 737 MAX 8 crashes and circumstances that led to it, the less funny it got. There were multiple whistleblowers along the way, and they were ignored and often fired[3]. The lack of good documentation was an outcome at the tail of a long and broken process of questionable ethics and missing accountability. This is not a problem that better documentation would have solved, or perhaps, to have the better documentation that could have solved even part of the problem, bigger upstream problems would have to have been solved first. I hate it when it turns out like this.


The 737 MAX in the January 5, 2024 incident was a 737 MAX 9. This is not like software where the 9 comes after the 8. They're different variants of a base model. This article has a pretty good explanation Boeing's 737 Max 9 aircraft: Here's what to know


I read or skimmed a bunch of articles while writing this post. I haven't quoted or linked all of them directly. Since I skipped over so much (so much) possible detail in the interest of focusing on the manuals, I'm including my reading list for those who want to go deeper.

The Aviation Herald, January 9, 2024

Boeing 737 MAX: Wikipedia

Report on 737 Max 8 crash blames Boeing design, Lion Air staff, October 25, 2019

Shauna GM's Mastodon thread about There Are No Accidents by Jessie Singer, April 12, 2023

Charlie Stross' Mastodon post about cockpit door opening during rapid decompression, January 9, 2024

2 years after being grounded, the Boeing 737 Max is flying again, June 19, 2021

U.S. pilots flying 737 MAX weren’t told about new automatic systems change linked to Lion Air crash November 12, 2018

What is the Boeing 737 Max Maneuvering Characteristics Augmentation System?, November 13, 2018

[1] Automatically opening the cockpit door in the event of decompression sounds weird, but it's a good thing, as Charlie Stross explains in the Mastodon post. Basically, it makes it possible for someone from the cabin to enter the cockpit if the pilots have become incapacitated and the plane is out of control, potentially preventing a crash.

[2] I couldn't figure out if the manual was missing the information or if it was communicated in a way that didn't make enough of an impression for the crew to remember it.

[3] "Further investigations also revealed that the FAA and Boeing had colluded on recertification test flights, attempted to cover up important information and that the FAA had retaliated against whistleblowers." Boeing 737 MAX Wikipedia article