4 ms·

Somebody told me that the quality of a company is directly proportional to the quality of its documentation...

thfuran 1y ago
I guess mathworks is one of the best companies ever.
makeitdouble 1y ago
Boeing's documentation is probably excellent. In general it is assumed that documentation is the boring part and paying attention to it is a sign of quality. But where do you put people who prefer writing and/or teaching to thinking long and deep about product issues ?
- reactordev 1y ago
  You encourage them to blog about it and you aggregate the posts into documentation - somehow. (I'm sure there's people for that, or an AI, or something). They had to explain it when they implemented it - explain it on a post. Confluence. Somewhere. You're right though.
- unscaled 1y ago
  Perhaps the biggest issue with the 737 MAX was lack of documentation. Boeing consciously chose to completely omit several new features (most notoriously MCAS) from the pilot manuals in order to make it seems like nothing important was changed that would require retraining 737 NG pilots on a simulator. In a sense, this is far worse than what most tech companies do since it is a life-and-death issue and Boeing has made a very conscious effort to hide details here, rather than just being lazy.
  - cpgxiii 1y ago
    One could say that "the point" of MCAS was to be an implementation detail, something that you would often deliberately hide from software documentation so that users don't design around internal details. There's something of a history of aerospace vendors omitting "implementation details" that end up contributing to serious accidents (e.g. if you get an Airbus far enough out of the normal envelope protections, you lose stall warning), and an equally sordid history of flight and maintenance crews improvising procedures to the observed (rather than designed/specified) behavior of aircraft systems. Arguably, the single biggest systematic risk in the current pilot training system is that crews overlearn to the implementation details of their training, rather than the actual principles and flight manuals (e.g. training inadvertently training for quick engine shutdowns, when the consequences of shutting down the wrong engine in reality are much more serious).
    - sofixa 1y ago
      > There's something of a history of aerospace vendors omitting "implementation details" that end up contributing to serious accidents (e.g. if you get an Airbus far enough out of the normal envelope protections, you lose stall warning), And Airbus control laws and protections are well defined and studied by pilots training for them.
      - cpgxiii 1y ago
        They are now, just as MCAS behavior is well-defined and covered in conversion training now. They were not covered as well prior to AF447.
- eru 1y ago
  Tech writer. Google famously employs quite a few of them for internal documentation.
- serf 1y ago
  >Boeing's documentation is probably excellent. it isn't, it's just ISO/NADCAP conforming.
- jiggawatts 1y ago
  I've read one of the manuals for the 787 management software stack, and it was... beautiful. It read like a novel. I read it twice on the train for the simple pleasure of it.
dlivingston 1y ago
Microsoft has excellent documentation. So that's one counterexample. :)
- cosmotic 1y ago
  It was excellent. It's a mess last time I looked.
  - userbinator 1y ago
    Their documentation for the very newest stuff contains very obviously AI-generated inaccurate and misleading crap.
    - userbinator 1y ago
      Don't believe me? Go look at it yourself. They've even "edited" the old docs with AI slop. https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/transfer-data-to-isochronous-endpoints https://learn.microsoft.com/en-us/windows-hardware/drivers/u... "The characteristics of the endpoint determine the size of each packet is fixed and determined by the characteristics of the endpoint."
      - WithinReason 1y ago
        If they used AI the sentence would be coherent
      - noname120 1y ago
        That sentence was already there _at least_ since Dec 2022, stop seeing AI everywhere. https://web.archive.org/web/20221214171028/https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/transfer-data-to-isochronous-endpoints https://web.archive.org/web/20221214171028/https://learn.mic...
        userbinator 1y ago
        They were using an automated editing tool before that.

I guess mathworks is one of the best companies ever.

Boeing's documentation is probably excellent. In general it is assumed that documentation is the boring part and paying attention to it is a sign of quality. But where do you put people who prefer writing and/or teaching to thinking long and deep about product issues ?

reactordev 1y ago
You encourage them to blog about it and you aggregate the posts into documentation - somehow. (I'm sure there's people for that, or an AI, or something). They had to explain it when they implemented it - explain it on a post. Confluence. Somewhere. You're right though.
unscaled 1y ago
Perhaps the biggest issue with the 737 MAX was lack of documentation. Boeing consciously chose to completely omit several new features (most notoriously MCAS) from the pilot manuals in order to make it seems like nothing important was changed that would require retraining 737 NG pilots on a simulator. In a sense, this is far worse than what most tech companies do since it is a life-and-death issue and Boeing has made a very conscious effort to hide details here, rather than just being lazy.
- cpgxiii 1y ago
  One could say that "the point" of MCAS was to be an implementation detail, something that you would often deliberately hide from software documentation so that users don't design around internal details. There's something of a history of aerospace vendors omitting "implementation details" that end up contributing to serious accidents (e.g. if you get an Airbus far enough out of the normal envelope protections, you lose stall warning), and an equally sordid history of flight and maintenance crews improvising procedures to the observed (rather than designed/specified) behavior of aircraft systems. Arguably, the single biggest systematic risk in the current pilot training system is that crews overlearn to the implementation details of their training, rather than the actual principles and flight manuals (e.g. training inadvertently training for quick engine shutdowns, when the consequences of shutting down the wrong engine in reality are much more serious).
  - sofixa 1y ago
    > There's something of a history of aerospace vendors omitting "implementation details" that end up contributing to serious accidents (e.g. if you get an Airbus far enough out of the normal envelope protections, you lose stall warning), And Airbus control laws and protections are well defined and studied by pilots training for them.
    - cpgxiii 1y ago
      They are now, just as MCAS behavior is well-defined and covered in conversion training now. They were not covered as well prior to AF447.
eru 1y ago
Tech writer. Google famously employs quite a few of them for internal documentation.
serf 1y ago
>Boeing's documentation is probably excellent. it isn't, it's just ISO/NADCAP conforming.
jiggawatts 1y ago
I've read one of the manuals for the 787 management software stack, and it was... beautiful. It read like a novel. I read it twice on the train for the simple pleasure of it.

dlivingston 1y ago

Microsoft has excellent documentation. So that's one counterexample. :)

cosmotic 1y ago
It was excellent. It's a mess last time I looked.
- userbinator 1y ago
  Their documentation for the very newest stuff contains very obviously AI-generated inaccurate and misleading crap.
  - userbinator 1y ago
    Don't believe me? Go look at it yourself. They've even "edited" the old docs with AI slop. https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/transfer-data-to-isochronous-endpoints https://learn.microsoft.com/en-us/windows-hardware/drivers/u... "The characteristics of the endpoint determine the size of each packet is fixed and determined by the characteristics of the endpoint."
    - WithinReason 1y ago
      If they used AI the sentence would be coherent
    - noname120 1y ago
      That sentence was already there _at least_ since Dec 2022, stop seeing AI everywhere. https://web.archive.org/web/20221214171028/https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/transfer-data-to-isochronous-endpoints https://web.archive.org/web/20221214171028/https://learn.mic...
      - userbinator 1y ago
        They were using an automated editing tool before that.