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:

  1. Updating dependencies is good.
  2. Now, look at the console.
  3. Considering this result, think about another action you might take.
  4. You can remove it, and you ought to understand the consequences.
  5. Here’s some detail on how it works.
  6. Change a giant conditional to true!
  7. Be fast at committing code.
  8. In the real world, no two teams are going to use their data tools in the exact same way.
  9. For the salvageable tests, take a minute and fix them.
  10. Fix the commands and clear out the mail.

And the LLM-generated STE sentences:

  1. Update the dependencies.
  2. Look at the console.
  3. Examine the result. Then, determine the next action.
  4. You can remove it. Make sure that you understand the consequences before you remove it.
  5. The following information explains how it works.
  6. Change the large conditional expression to true.
  7. Commit the code promptly.
  8. Each team can use its data tools differently.
  9. Repair the tests that you can repair.
  10. 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.