This week a colleague taught me about Simplified Technical English in the context of agentic software development. I’m fascinated by technical writing techniques, so I intend to explore this.
To start, I took ten instruction-like sentences from this blog, and asked ChatGPT to convert them to STE.
Here’s what it came up with. The original sentences:
- Updating dependencies is good.
- Now, look at the console.
- Considering this result, think about another action you might take.
- You can remove it, and you ought to understand the consequences.
- Here’s some detail on how it works.
- Change a giant conditional to true!
- Be fast at committing code.
- In the real world, no two teams are going to use their data tools in the exact same way.
- For the salvageable tests, take a minute and fix them.
- Fix the commands and clear out the mail.
And the LLM-generated STE sentences:
- Update the dependencies.
- Look at the console.
- Examine the result. Then, determine the next action.
- You can remove it. Make sure that you understand the consequences before you remove it.
- The following information explains how it works.
- Change the large conditional expression to true.
- Commit the code promptly.
- Each team can use its data tools differently.
- Repair the tests that you can repair.
- Correct the commands. Then, delete the mail.
The goal is short, literal, direct, unambiguous, and action-oriented writing. I like most of these more than the originals, but I think you lose some of the fun of blogging if the writing becomes too much like a manual. For the right kind of project, I’d consider adopting this.
Read more here: ASD-STE100 Simplified Technical English.