Writing about Writing

Feb 27 2018

This is it, the first of what will hopefully be many more (regular) articles. I’ve fallen out of the habit of writing, and it’s something that I regret, because the ideas for new articles never stopped, they just rattled around in my head instead!

For this first article, I’m going a bit meta, and writing about “writing”. More specifically I’ll be digging into why, as developers I think we should be writing more, what stopped me and what you can expect to see here in the future.

Developers !== Writers — or do they?

It seems appropriate to ask, “Why should developers write?” — after all, that’s what writers do, not developers! I’d argue that everyone should write, if only to help them make sense of the world and what’s going on in their life. It doesn’t need to be published, elegant or even written in full sentences, but the process of mapping out your thoughts on paper has so many benefits. Organising your thoughts is not only useful, but also relaxing. Any method will do, but pen and paper really is the correct medium if catharsis is the aim.

Of course, all this writing has the potential to turn us into a cohort of naval-gazing, angst ridden introverts. After all, we’re developers of the 21st Century, what happened to moving fast and breaking things? I think we all know now that this approach can lead to poor and even unethical decisions. Asking developers to think through some of the consequences of their everyday decisions might not be such a bad thing after all.

As developers and designers we’re given an odd position of authority as the gatekeepers to what ends up out there in the world. This is a position that we should be taking more seriously, and part of that requires us to be in tune with society, have a working moral compass and an accurate map of the issues we’re trying to navigate.

We need to understand our own values, and those of the people around us to best create something that fulfills those needs, without violating our shared, implicit code of ethics. Writing is something that helps us better understand the problems we’re trying to solve at a human level. Without it, we can easily become bogged down with only solving it at a technical level, and become blind to the consequences that may have.

Of course, writing code is a core developer skill, and will remain so for a long time to come. Coding is all about communicating with the computer, but the result is almost always abstracted away from the goal it’s working towards and the values acting as it’s constraints.

Writing is about communication with people, even if that’s just ourselves. Even before we took to the internet to argue over discuss our favourite JS framework, as a profession we were often required to produce documentation for the software we wrote. It always seemed secondary to the real work though, so we never put the same time or care into it as the code we wrote. Perhaps this explains why the documentation around software is almost always crap, and reads like it was not meant for humans, but for the computer too?

Thanks to the rise of blogging and more recently platforms like Medium, developers can now spend as much time writing about software as they do writing the software itself. Like me, you probably learnt a lot of what you know from blog posts, tutorials and even full blown courses or books. It’s brilliant that as a profession, we share how to get better, what constitutes best practise, etc; often available for free, to anyone and is undoubtedly a force for good.

These examples however are the wheat amongst the chaff, and we’ve got a lot of chaff! The other writing we indulge in is a lot of developers arguing, hyping and even outright bullying with their words.

As a profession, we’ve always been prone to our “religious wars” — Vim vs. Emacs, Space vs. Tabs, etc — but they are often lighthearted and well natured, even if they looked serious on the face of it. However, I’ve noticed that developers being openly critical of each other’s work with very little to substantiate it is something new. We seem to enjoy drawing lines in the sand and create real “us & them” scenarios around the way a particular project or framework goes about its business.

There seems the need to defend what you feel is the correct approach to a problem, and violently attack other approaches and their creators. This shit-posting can be seen on the GitHub issues pages of most open source frameworks unfortunately, even against prominent and successful authors with a proven track record.

To a degree, this is the new normal the world over: opinions supported by paper-thin arguements, yet strongly fought for when confronted by an alternative.

This makes a lot of the content around web development — front-end and JS in particular — incredibly noisy. It’s moved from a debate to a shouting contest. This is both the cause and the response to the never ending hype train that our industry seems to have endured the last few years. What’s more disconcerting is the venom I see from many quarters. This is often directed at those writing about, or building anything that contradicts the authors currently held beliefs, and is yet another issue that the open-source community needs to get in hand before it drives too many maintainers away.

Junior developers are often encouraged to document their learning experiences, solutions or even musings, but never has it been so intimidating to do so. Say the wrong thing and there are dozens of commenters from Hacker News, Reddit & Twitter that will gladly tell you just how wrong you are.

Much like political debates, it’s easy to abstain and just let the conversation roll on by without responding to the shouters. You can sit there quietly reading what they have to say without saying anything yourself because you’re confident in the knowledge you’re right and don’t need to prove it.

The issue with this approach is that we create an echo chamber for the shouters and remove any possibility of debate to leave a one-sided conclusion for the next person hoping to find an answer to this issue.

This doesn’t help us as a community or a profession move forwards. We just get stuck in a cycle of hype, anger and in-fighting. Instead, we should all be talking together, even if it means adding to the noise.

Why should a developer start writing?

If we put aside any glorious missions to make the conversation within our profession a utopian picture of democracy; there’s some really good reasons to write.

Often, when I’ve got stuck on something, I like to write a few notes about the issue, and how I resolved it. If my solution is less than perfect, or has some trade-offs, I write about the alternatives and why I picked the one I did.

That’s the sort of byproduct created from learning something new that isn’t always obvious in the end result. The code that I write as a result probably won’t explain the choices I made or the journey I went on to get there.

An answer to any question in our profession is almost guaranteed to be “it depends”, so this additional documentation is invaluable to look back on when confronted with a similar issue again. In this new context, the same solution might not be the right one, but one of the alternatives you looked into before could fit the bill.

By documenting your learning, you can save yourself the time and frustration of relearning it (or blindly applying the wrong solution) in the future.

What’s more, this record of your learning can be useful to others too! You can share it and help someone else understand the problem and the array of possible solutions. This is even more useful when the decision is higher level and perhaps more conceptual than specific and technical. When you’ve made a decision based on a higher-level value, it’s unlikely that the code will communicate those values without substantial investigation.

The important point here is that we need to be talking about the “whys” more, and less about the “hows”. The end result is often absolute with little room for discussion, and even less transparency.

Instead, talking about the logic and the reasons behind our solutions prompts better communication and understanding between people. Even where the solution is wrong, or suboptimal; explaining the logic behind it creates the opportunity to have the solution debunked without resorting to an all out flame war.

Think back to the last “debate” you witnessed online about development. How much of it talked in absolutes?

“Solution X is better than solution Y.”

— or even worse —

“Solution X is better than Solution Y because \ said so…”

How much of it was contextual and substantiated?

“In this sceanario where factors 1, 2 and 3 are present, solution X is preferable to solution Y because of A, B and C.

These types of discussions rob us of the chance to practise reasoning from first principles, and understanding how someone else came to a particular solution.

My relationship with writing.

The handful of articles that are already published here are the result of my previous attempts at writing. Many more never got beyond a scribbled note somewhere, let alone a draft with the ideas fleshed out.

I’ve always had an up & down relationship with writing. At school I took a few subjects that had a really strong emphasis on clearly articulating opinions, supporting them and drawing balanced conclusions in longform writing.

When I started my English A-level, my teacher was a lovely Scottish lady but with a fierce reputation for blunt criticism. She left me under no illusions that my writing was not up to scratch. I can’t remember the specifics of the feedback, but I remember the punchline: sort it out or you won’t be here next year!

Fortunately, the type of writing that was required of me in my Business Studies class had a strong structure and format that I instantly understood and was able to apply to my writing elsewhere. It required me to explain the fundamentals of a situation, make arguments both for and against a given point of view and then draw a conclusion supported by the facts and my reasoning. This structure suited me, and surprisingly was exactly what was needed in my English class too!

As a result, I’ve been left with a very formal, analytical tone to my writing; even when it’s not particularly appropriate. My attempts at writing light-hearted, informal marketing copy have always fallen a little flat. Whilst it’s not the way I talk, as soon as I sit down to write, I fall back to my old, structured format that served me well.

The result is that whenever I try write in my natural, conversational voice, it ends up a contorted mess of humour and “Year-end” report. When I reread it I almost always hate it, and either leave it sitting as a draft forever or instantly delete it.

Writing is hard

What I’m trying to illustrate through that perhaps long-winded story is that writing is hard, and it’s a skill that needs to be practiced. Just because you can write in one context doesn’t mean that you’ll be able to write in another.

As a developer, I’ve never before been able to justify the time required to improve my writing and bring it in line with my personality and voice. Unfortunately, this has a predictable conclusion — my writing never improves. This is something that I really want to improve on now that I’m working for myself, and will find myself needing solid copywriting skills far more regularly.

I’ve previously talked about how I’ve removed Google Analytics from this site. One of the reasons was that it wasn’t really tracking anything of importance, but another was that it clearly highlighted the deafening indifference every time I posted something new.

I found that hard, even though I knew logically that a website with a handful of incredibly mediocre articles and zero Google-juice was never going to be a traffic magnet.

The problem was that I was often posting something, not because I had something to say, but because I wanted to add my tuppence worth to a current issue, and perhaps get some of the attention that issue was receiving.

This is probably the worst reason to start writing online.

Finding something to write about

Often I’d write response to another article that I had just read and heartily agreed with. Wanting to communicate the same values that the original had, and lacking my own voice or experience to add context to the subject — my copy-cat article always read very much like a “me-too” article.

Fortunately, now that I’m no longer the inexperienced junior developer I was back then, I’m less prone to the “me-too” way of thinking. A few years experience of different technologies has given me war-wounds and opinions of my own.

Whilst they might be similar to many others, and I’m still capable of writing a “me-too” article, I can now support and justify my opinions with first hand experience, which gives me something unique that I can add to a conversation.

Writing, unless it’s strictly academic, is ultimately about communicating your experiences and worldview to someone else. Without those experiences and your own unique take on them, you won’t have developed any opinions, so you’ll have nothing to write about!

Why write long articles?

These days, if you’ve got an opinion that you want to put out into the world, you reach for your social media network of choice. You’ll probably pick a network based on your preferred medium (words/images/video), but what you publish will almost certainly be the briefest of glimpses of what the world looks like from your shoes.

Whether you’re constrained by a character limit or just the attention spans of those reading your post, your opinion is going to be a short, truncated version of its true self.

Proponents of social media will argue that this brevity is important, that it concentrates your thought into the densest and simplest version possible. I’ll agree: “dense” and “simple” are two words that often spring to mind when I scroll through these feeds.

The simple fact is that no social network I know of allows you to unpack your thoughts, explore them and present a nicely rounded conclusion quite like the long form article. I suspect it’s why Medium has become so popular. It gives all of the advantages of having your own blog where you can write to your hearts content, without all the messy business of building or setting up your own site.

In a world of “drive-by Tweetings” that leave you dazed and confused, I think that long articles provide some much needed solace and is perhaps the antidote to a lot of what ails modern society.

Longform helps understanding

It’s no secret that everyones attention spans are getting shorter. Smartphones and a feed of mildly-interesting yet largely useless information has been an incredible one-two punch in destroying our ability to just sit with our own thoughts. Even the briefest of moments, like waiting in a queue, now has to be filled with a quick refresh of the latest happenings.

The problem is that just like the brevity of social media, this fragmented interaction with new information doesn’t allow enough time to communicate anything but the most basic form of the idea or any time for us to digest and make sense of it. There’s no room to justify ideas, or add context to an eye-catching headline — we simply don’t care for anything that asks too much of us anymore.

Sidenote: Slack is another example of this. Without the time or space to respond properly, most conversations are made up of people’s instinctive responses. I’ll let you decide if that’s a good thing or not…

The result is a dialog made up of blunt, extreme views. These views are often so absolute that they leave no room for ambiguity or exceptions, so instead of prompting debate they prompt conflict. The discussion, if there even was one to begin with, almost certainly descends into a frenetic and unfocused argument where neither side learns anything, and only become more deeply entrenched in their own views. No conclusions can be drawn from this type of discussion, other than we’ve lost the ability to communicate like adults.

The Hype Train

I also think that the above behaviour is one of the reasons that we’ve seen so much churn in our industry the last few years. Instead of measured and reasoned decisions, developers are making knee-jerk ones based on sound bites, and the preferred technology rapidly changes as they respond by jumping on (or off) the hype train.

For a profession that prides itself on logic and data, we seem incredibly willing to make large decisions that impact the future of our project or company with a complete absence of either; instead relying on who can shout the loudest.

I’ll confess to being guilty of this myself. I rode the Javascript hype train that a few years ago looked set to send a good percentage of our profession completely round the bend. We were suffering from JS fatigue and were all feeling a bit burnt out from the experience.

I now consider myself part of the “old & cynical” group of developers that are skeptics of anything new, having been burnt a few too many times by technology that’s been over-hyped. It’s weird that as a 28 year old, with only 6 years professional experience I’m part of the grumpy old man club when there’s so many developers out there who have been doing this longer than I’ve been alive!

I’m sure these seasoned developers were there, talking about these new technologies with a measure of reserve that they learnt from years of experience. If they were there I never heard them, either because they were very quiet or because I didn’t want to listen — I’m not sure.

If instead of endless Medium posts hyping the next big thing, there were some long, well supported and reasonable arguments dismantling them then we might not have hit JS fatigue at all. Whether we would have listened to these measured warnings is another issue. Ours is an industry not known for respecting it’s elders, instead valuing the innovation that youth seems to promise. As a result, we talk breathlessly about the latest development, that is in fact just a rehashed version of something that’s already been tried and had it’s flaws found.

In short, I think a more vocal commentary from the old guard that isn’t instantly dismissed could have saved developers a lot of frustration and angst the last few years, and longform articles would have been the perfect, timeless medium to record those lessons.

What to expect from me?

What does all this mean for this site?

Well, I’ve got a good backlog of things to write about. As I said at the start, just because I stopped writing, doesn’t mean the ideas did. At present it looks like I’ve got around thirty good topics I want to dig into, some of which might turn into a couple more.

The subjects are going to range from tangible “nuts & bolts” stuff like some of the lessons I’ve learnt, patterns or approaches I’ve found useful, technologies I like, tutorials etc. to commentary on our work as developers and where I see it fitting into business and society.

As I’ve said, my writing here is mostly for me, but I hope that others might get some enjoyment or new ideas from what I publish here. If there’s something that you’d like to read more about, then do let me know.

My aim is to post something here every Friday afternoon for the next six months. I’m giving myself a regular publishing schedule to hopefully make writing regularly a habit.

At some point in the near future I’ll also be sending out a fortnightly newsletter with links to other articles or projects I’ve found interesting or useful, along with my two most recent articles. If that’s something that interests you, then please do sign up below!

Here’s to more writing (and less writing about writing…).