I used to write technical manuals for aircraft and this really takes me back. At one point in time there was an endless debate about whether or not the company I was working for would adopt STE100, S1000D, or both. At the time software support for both standards was poor. I haven't kept up on software for this niche since then so I can't say if it is any better.
From my perspective STE100 is intended for things like the aviation industry, where everything is in English, but non-native English speakers are involved in critical process like repairing and flying aircraft. I'm not sure it is really necessary anywhere else, but the fundamental concepts are reasonable. Keep your sentences short, avoid ambiguous terminology, and keep your vocabulary minimal.
I've been responsible for documentation in similar ways.
What I think is interesting here, is that with so much detail specified, tools could be created to write and check technical documents. I suspect with LLMs and the like becoming broadly available, that could also help.
On the other hand, I've seen technical documents that were accurate and correct, but they obfuscated more than clarified. One document I remember specified linker records with items like 0x54 instead of 'C' and end-of-record instead of '\n'. It seemed a little too pedantic instead of common sense.
From my experience technical documentation for aviation was made challenging by the corpus of engineering plans that were signed, initialed, and scanned into a PDF as an image. Modern machine learning to ingest that data and produce a diff would be very useful even if it still needed human review.
It seems there's been some effort to make it more broadly applicable. For example, some slides I found specifically mention they made effort to reduce examples from aviation in newer versions.
That said, for many applications following all of it is probably not worth it. It uses some very specific terminology with specific approved meanings for words that are commonly used. e.g "follow" can never be used in "follow these instructions", but in can be used in "follow the green lights to the nearest staircase". This makes a lot of sense, but sticking to one approved meaning for a hundreds of verbs and adjectives is hard word and requires specific expertise.
I'm still in that niche, and I hope I'm not being Debbie Downer, but no, the software is still horrible.
The only movement that's happening today is where individual ERP/PDM/ILS solutions are beginning to just incorporate the tech writing tools wholly into their ecosystem, rolling them up into SAP/Epicor/TeamCenter/Aras/etc. Or even into the CAD system[1]. Doing S1000D in Program X? Whelp, better get TeamCenter spooled up so you can do the writing and publishing.
What does that do for interoperability? Nothing good! But it doesn't matter - S1000D instances weren't interoperable to begin with. The one good thing from this, is that it might - and I do want to underline might - give the pubs team a somewhat better chance of optimizing their data flows from other business systems. Yeah. Might.
All this crap makes me think of Daniel Dennett's famous essay on Chmess. How "chmess" sucked in a whole generation of chess scholarship, with no one stopping the train for one hot second to ponder that they're blowing their entire careers optimizing something that never happens.
[1] Oh yeah, CAD for maintenance manuals. The engineering design system, that's a great place for parts lists.
Oh yeah, CAD for maintenance manuals. The engineering design system, that's a great place for parts lists.
This was always a fun one. We realized right away that the data in the CAD models was superior to the technical drawings we received as PDFs (most of which, awful scans of paper documents). However, only the technical drawings were acceptable for the type-certificate. Our manuals were part of the type cert, so we had to verify everything agains the crappy PDFs anyway.
Comments
I used to write technical manuals for aircraft and this really takes me back. At one point in time there was an endless debate about whether or not the company I was working for would adopt STE100, S1000D, or both. At the time software support for both standards was poor. I haven't kept up on software for this niche since then so I can't say if it is any better.
From my perspective STE100 is intended for things like the aviation industry, where everything is in English, but non-native English speakers are involved in critical process like repairing and flying aircraft. I'm not sure it is really necessary anywhere else, but the fundamental concepts are reasonable. Keep your sentences short, avoid ambiguous terminology, and keep your vocabulary minimal.
I've been responsible for documentation in similar ways.
What I think is interesting here, is that with so much detail specified, tools could be created to write and check technical documents. I suspect with LLMs and the like becoming broadly available, that could also help.
On the other hand, I've seen technical documents that were accurate and correct, but they obfuscated more than clarified. One document I remember specified linker records with items like 0x54 instead of 'C' and end-of-record instead of '\n'. It seemed a little too pedantic instead of common sense.
From my experience technical documentation for aviation was made challenging by the corpus of engineering plans that were signed, initialed, and scanned into a PDF as an image. Modern machine learning to ingest that data and produce a diff would be very useful even if it still needed human review.
edit: and by 0x54 I mean 'T' lol
It seems there's been some effort to make it more broadly applicable. For example, some slides I found specifically mention they made effort to reduce examples from aviation in newer versions.
That said, for many applications following all of it is probably not worth it. It uses some very specific terminology with specific approved meanings for words that are commonly used. e.g "follow" can never be used in "follow these instructions", but in can be used in "follow the green lights to the nearest staircase". This makes a lot of sense, but sticking to one approved meaning for a hundreds of verbs and adjectives is hard word and requires specific expertise.
I'm still in that niche, and I hope I'm not being Debbie Downer, but no, the software is still horrible.
The only movement that's happening today is where individual ERP/PDM/ILS solutions are beginning to just incorporate the tech writing tools wholly into their ecosystem, rolling them up into SAP/Epicor/TeamCenter/Aras/etc. Or even into the CAD system[1]. Doing S1000D in Program X? Whelp, better get TeamCenter spooled up so you can do the writing and publishing.
What does that do for interoperability? Nothing good! But it doesn't matter - S1000D instances weren't interoperable to begin with. The one good thing from this, is that it might - and I do want to underline might - give the pubs team a somewhat better chance of optimizing their data flows from other business systems. Yeah. Might.
All this crap makes me think of Daniel Dennett's famous essay on Chmess. How "chmess" sucked in a whole generation of chess scholarship, with no one stopping the train for one hot second to ponder that they're blowing their entire careers optimizing something that never happens.
[1] Oh yeah, CAD for maintenance manuals. The engineering design system, that's a great place for parts lists.
This was always a fun one. We realized right away that the data in the CAD models was superior to the technical drawings we received as PDFs (most of which, awful scans of paper documents). However, only the technical drawings were acceptable for the type-certificate. Our manuals were part of the type cert, so we had to verify everything agains the crappy PDFs anyway.