Communicating about the web
The longer that I work in web development, the more time I spend thinking about the communication that surrounds the work I’m doing. How do I talk about what I’ve done? How do I best explain how to use a feature or tool? What happens when I’m no longer working on this project? The language that we use, whether we’re talking to another developer, a designer, or a user, is really important.
For communicating with other developers, it just gets more and more important to be succinct. The fewer words I can use to explain something, the better. This is true in commit messages, code comments, and documentation. I know it’s important because I really appreciate it when others do it. It might take me a little more time to edit, but depending on how many people are involved, it can save a lot of others’ time.
Slowly over time, I’ve been trying to cut out my use of the word ‘just’ and other similar terminology. Others have said this, but it’s unhelpful in that assumes that a process is easier than it may be for the reader. It subtly gives the writer the role of the expert, when it would be better to attempt to meet someone where they are. It’s something I’m working on.
Beyond the day to day, I’m also challenged and interested in how to communicate to a larger, slightly undefined audience. In some cases, it’s hard to know who has or who will read what you’ve written. For on-boarding developers or users, how do I write broadly and generically while still being laser focused on the topic at hand? How do I write a commit or a pull request with enough information without taking up too much of my time? Or, how do I explain how to use a feature when my words could possibly be copied and shared with others?
The web is more fun when everyone is included, and that includes everything about the web. The more we build, the more we have to keep others in mind. After all, you don’t know where your next users will come from.