Writing   Documentation

My mistakes in writing descriptions

I’m contributing to an open-source project on GitHub called Awesome, a curated list of interesting topics and their resources. Famous open-sourcer Sindre Sorhus wants help in writing descriptions for each item on the list, so I created a pull request for programming languages in the list. I thought my contributions would be helpful. Not quite.

Mistake 1: Writing generic descriptions

I didn’t distinguish what made each programming language unique, so some of my descriptions were generic. For example, I wrote “C/C++ - General-purpose object-oriented language.” As Sindre pointed out, this doesn’t describe what is unique about it. There are hundreds of items on the list. If descriptions look similar, they won’t be helpful to users who want to tell these languages apart.

My new C/C++ description reads, “General-purpose language best for projects focused on low-level processing and fast applications for server-side software.”

Mistake 2: Describing where a language runs, not what it is

For the Swift programming language, I wrote, “Compiled programming language for iOS, macOS, watchOS, tvOS, and Linux applications.” While it describes where Swift runs, it doesn’t tell users what it is. Swift runs on Windows and will run on many more platforms in the future.

My new Swift description reads, “Apple’s compiled programming language that is secure, modern, programmer-friendly, and fast.”

I plan to update this blog post once the project owner approves and merges my pull request. He may want me to improve my descriptions further, and I welcome his input. To be a better technical writer, I must be open to feedback.

Update: Sindre merged my pull request and also edited the C/C++ description, which now reads, “General-purpose language with a bias toward system programming and embedded, resource-constrained software.” In the future, I’ll make sure my writing is more specific. I shouldn’t forget that users may not have heard of these programming languages at all, so bombarding them with generic descriptions is not going to help.