It will never cease to amaze me that standards bodies whose sole purpose is to help everyone coordinate by creating and distributing a standardizing document that everyone involved should read and conform to are so reluctant to share the document. Here, they offer to email it to you if you ask nicely in the form of emailing an Excel file, and that's unusually permissive. Surely some of these standards bodies should be interested in proactively telling people what their standards are.
STE used to cost $2900 USD for the print copy. So . . baby steps, I guess?
STE, unlike Simplified English or International English or its many cousins, has what I like to call the "ISO Kiss of Death". Basically, with IKoD, you get a cabal that takes over a spec, and then it defends the spec like a kung fu master defends his secret style. Thing is, the cabal also mandates how documents get written, so now you have to go to the secret Kung Fu School to learn the Secret Style if you want to, yknow, deliver a product.
This can go on for decades, multiple decades, before something maybe breaks the chain - some busybody in procurement, or a major national embarassment, or an overactive journalist revealing how making a PDF file managed to cost two hundred million dollars. Or someone raising their hand and saying, um, sirs, very sorry to interrupt, but this is all common capability in the Lands Outside the Secret Temple.
Fighters from secret temples never amount to much.
Sounds interesting, but the website is lacking. I'd've liked to see real-life examples of texts rewritten using STE, as well as comparisons to other widely-used style guides. And just give me a fcking download link.
While I appreciate this being shared, I sure hope the nice people at technicalwritingexpert.com have the "written authority of an officer of ASD" to reproduce and/or publish this information!
The all caps, imperative examples remove me of old school text adventure commands. In fact, that’s how I try to write my own to-do lists or project milestones: VERB [ADJECTIVE] OBJECT (e.g. GET LAMP). If I can’t reduce a task or milestone name to that level of abstraction, then it can probably be broken down into smaller steps. Plus it’s a fun mental challenge. :)
It's interesting to me how doing this for technical documentation feels like a smart idea and makes me happy, but doing this for non-technical communication immediately sets off every 1984-style dystopia alarm in my brain.
Nothing 1984 about it. It is for situations where English is the standard, but a non-native speaker might be involved or it is otherwise important to avoid ambiguity. As an example, when this standard was written it was common for small business jets to have the complete printed maintenance manual stowed in a drawer somewhere on the aircraft. The manuals explain step by step how to do every major repair or replacement. They were also essential to things like Time Limits and Maintenance checks, which might have to be done at your destination rather than home base.
I like the idea of these. As a native English speaker I'd be more comfortable with a sort of code/dialect switch when talking to ESL speakers, rather than worrying about them when I talk normally.
Like let me keep my language the way I want to speak it, and let me use this with a broader audience for the purpose of global communication.
There are additionally certain ways sentences are to be constructed that are beyond the means of simple spellcheckers. The accepted vocabulary list is the easy part of the spec.
I like the idea and want a software tool that helps me write STE as a hobbyist. It's not the first time I've found friction with ESL folks with some of my vocabulary.
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.
WOW! They really streamlined their operation. Last time I looked at their site you had to send an e-mail to a certain address, with the subject line "REQUEST COPY" (had to be exact) and the body containing your phone number. You'd then get an SMS with the URL of a WEBP image of a QR code, which resolved to a Gemini address of a document (formatted in the HP Printer Command Language (PCL)) describing detailed instructions on how to construct an Excel spreadsheet in the correct format to form a request to get the Simplified Technical English document, along with the address where to send it.
Now it looks like they just give you the Excel spreadsheet. What a good idea! And you might not even have to print it any more.
I hope they are putting all the saved time to a good cause.
I can’t emphasize enough how important a technical English standard is. I’ve been reading these manuals for a high end industrial document and it looks like it was written by a ten year old. No conceptual information, no continuity, and various street talk style instructive sentences.
Makes sense though. Some learning English might only understand "run" in the sense of something people do outside, so the latter statement would be less ambiguous.
"Run the program" is eventually generalized into "Run the $1" and someone assigns it "plate", and I as an i18n end user obtain to rotate apertures on escaping dinnerware. A license plate cannot be operated and that's one less ambiguity gone before it happens.
I get why these technical expressions counter productive, they create uneven cognitive load on speech center in the brain rather than distributing interpretation task wide across from visual and motor and various cortex that would be readily available. But that's the goal; to minify dependency graph and remove variances coming from implementation differences.
I move in these military/defense spec circles rather a lot, and yeah, ASD has come light years when it comes to ASD-100 (STE) availability. Cruise this thread and you'll see quite a few of the horror stories users have had just getting their hands on a printed copy of the specification. Why, you might ask, why in the dickens was this arrangement so resilient? Whelp, it goes back to the governance of these specs, and the ugly truth is that if the national military sits out the technical steering, and then the big OEMs sit out the technical steering, the only ones left are the existing software vendors. So that probably tells you all you need to know about how that goes.
I'd also like to give a shout out to TechScribe.uk, who sells a LanguageTool package to use STE as a LanguageTool grammar and language set. RedPen.CC also has some STE rules you can plug into the linter. RedPen and LanguageTool, you can integrate those with Visual Studio Code or another standard text editor. Of course, if you're tasked with STE, then you probably also have the budget to go to the Big Boys, Etteplan (formerly Tedopres) and those fellas, who are in the spec governance up to their elbows. There's a reason licenses for aerospace techpubs can easily clear 50k per seat per year - and the reason is crap like that.
41 comments
[ 3.6 ms ] story [ 96.4 ms ] threadSTE, unlike Simplified English or International English or its many cousins, has what I like to call the "ISO Kiss of Death". Basically, with IKoD, you get a cabal that takes over a spec, and then it defends the spec like a kung fu master defends his secret style. Thing is, the cabal also mandates how documents get written, so now you have to go to the secret Kung Fu School to learn the Secret Style if you want to, yknow, deliver a product.
This can go on for decades, multiple decades, before something maybe breaks the chain - some busybody in procurement, or a major national embarassment, or an overactive journalist revealing how making a PDF file managed to cost two hundred million dollars. Or someone raising their hand and saying, um, sirs, very sorry to interrupt, but this is all common capability in the Lands Outside the Secret Temple.
Fighters from secret temples never amount to much.
It's still pretty mad!
Like let me keep my language the way I want to speak it, and let me use this with a broader audience for the purpose of global communication.
Looks like there are some here https://www.techscribe.co.uk/techw/asd-simplified-technical-...
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.
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.
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.
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.
Now it looks like they just give you the Excel spreadsheet. What a good idea! And you might not even have to print it any more.
I hope they are putting all the saved time to a good cause.
Web developers: Kindly try and not override browser scroll behavior.
I get why these technical expressions counter productive, they create uneven cognitive load on speech center in the brain rather than distributing interpretation task wide across from visual and motor and various cortex that would be readily available. But that's the goal; to minify dependency graph and remove variances coming from implementation differences.
I'd also like to give a shout out to TechScribe.uk, who sells a LanguageTool package to use STE as a LanguageTool grammar and language set. RedPen.CC also has some STE rules you can plug into the linter. RedPen and LanguageTool, you can integrate those with Visual Studio Code or another standard text editor. Of course, if you're tasked with STE, then you probably also have the budget to go to the Big Boys, Etteplan (formerly Tedopres) and those fellas, who are in the spec governance up to their elbows. There's a reason licenses for aerospace techpubs can easily clear 50k per seat per year - and the reason is crap like that.