I am by no means a great writer, but I am now much better than I was and yet still have with me the guide that got me here.

It takes something to be great and yet another to be able to distill that knowledge into transferable learnings. My prose might not be what you’re aiming for, but if you’re where I was, my advice will probably still be of some use to you.

Before we begin, you might be wondering why this article is “for developers”. What about a guide to writing can be so targeted?

#For Developers

You may have thought this is a guide to writing docs. It is not. The developer’s main contact with literature being through documentation is exactly why I have made this guide.

You have been exposed to a particular form of writing. Your mind has been sullied - your pen misshapen. You have warped your idea of information exchange to be all encompassing. You’re boring.

But you might already know this. If you’re reading still, you are either intrigued by my accusations or wholly identify with them. This was my problem. I wrote docs. I wrote boring articles. It was quick, it was dense, it was efficient. And no one read it.

To write something that is read takes more than being correct. You need to be interesting. And I wasn’t.

It was hard to write more than a sentence when I was tackling articles on technical topics. What are the options you have when implementing this feature of our API? Here are several with their associated benefits - pick one. What more could I say? Would you rather I add 20 paragraphs of filler like I was writing a recipe on Epicurious?

Perhaps it’s fine. It’s possible the topic you picked didn’t have much depth to it. But if your article requires any bit of length, it’s likely hard to get through. Writing in that same droning tone throughout like you’re describing a function interface isn’t doing your work any favors.

#It’s The Docs

You are writing articles like you write docs. Do you read docs the whole way through? No? Then why do you assume everyone else will jump at the chance to read your own technical drivel?

Docs have been hurting your writing because it puts you in a different realm of information exchange.

Documentation is meant to be skimmed. Skimming is made more efficient when content is dense and exact. Writing articles, even technical ones, often explores a different kind of communication medium. You’re not just expressing an idea, but a narrative.

Our language is not simply programmatic. You must understand that there is an emotional context to the rhythms and references. There are concepts that words alone cannot explore - sometimes you have venture into the real world and discover them firsthand. Similarly, the direct definition of speech is often not enough to communicate the emotional context you want to impart. You need a narrative - or, if not that, a narrator.

#Getting Better

Hopefully I have done enough to explore your affliction. Now, for the reason you started reading to being with - the solution.

You need to write. It’s not satisfying, but it’s true. You need to write a lot. However, and I’m sure you know this, but it is not enough to write without direction. You will still improve, but it will take significantly longer to find your stride without guidance.

A technique that was tremendously helpful in my own journey was speech-to-text services.

You’re likely in considerably better shape when it comes to talking as opposed to writing. I grew up in a pretty dense city with enough going on that you had to be somewhat interesting to hold the floor. You might not get directly ignored, but you could feel that you didn’t have everyone’s full attention.

You don’t have to write like how you talk, but it’s a very good start. Try it! I found my writing almost instantly improved through this process. I used my phone’s built in speech-to-text and just dictated my thoughts along with the necessary punctuation. Some people advise speaking your writing aloud to yourself to see how it feels. This skips that whole step because it originally came from your throat anyway.

You’ll find some sentences jarring in their length. People speak in varied ways - this is good! There’s a writing style I see from people who seem fresh out of high school, having never done a lick of creative writing outside of what was academically demanded. They write “In this article I will talk about” in their intro. They write “In conclusion” in their final paragraph. It’s boring - it’s extra - it’s draining to read.

Your writing should surprise the reader. Practice avoiding cliche. Play with sentence length. Ignore the rules of grammar!

But I was told I should never start a sentence with a conjunction! And they don’t like it in academics either! They say “quotes should wrap the punctuation”.

I’ll tell them sorry for you. Writing is art. Do not constrain yourself by what is so blatantly an artificial restriction on emotional representation. Your writing should at its best be a reflection of your worldview and Qualia. You are given the power to erase sentences - to rethink ideas and explain them in the way you would best like to. You can spend hours rewriting - a luxury you never have in real time.

Showcase your passion. Describe your mind. Build up the world in your eyes as you see it. Present the framing you are stuck with to a world looking through cracked glasses. Share your vision so that others may finally see.

#Your Task

This abstract rambling may have lost some of you. If you’re the straight-laced illiterate software engineer I’ve made you out to be - a reflection of my past self - you may need some more specific instruction.

Start keeping a journal. It doesn’t need to inhabit any one medium. It can be voice notes, physical paper, or a Google Doc. But you should practice speaking your mind. This is not the time for editing - you are allowed no refinement. Write your heart out to a void with no embellishments. Do not polish what should at this point be a rambling directionless mess.

Put your soul into your work and then never look at it again. If you have trouble writing, it’s probably because you don’t write enough. Do not be afraid of running out of ideas - new ideas will come just as you finish verbalizing the ones you have. But you need to write.

At first, you will feel yourself constrained by social expectations to speak politely. No one is reading this. You can delete it right after if it makes you feel any safer. Let go and speak freely. You must. You must speak your mind or forever stay as your are.

Write about your close relationships. Your thoughts on philosophy. The correct way to approach cooking. Talk about your day. Isn’t work stressful? What most bothers you? Are you good enough? Does it make you feel little? Write it and put it to rest.

As a side effect, this process can be incredibly therapeutic. I find that verbalizing a lot of what makes me uncomfortable gives me a better vocabulary in tackling my insecurities. It manifests as some confidence over the problem. Even if unsolved, just speaking out all the issues at least gives me visibility over what truly frightens me. What’s more scary than the monster you know is the one you only know is nearby.

#The New You

In time I hope you are equipped with a new power. So you write better articles on clamping techniques now, sure. But you have also transformed. There is something different. Intangible, but plain as day. Almost offensively obvious.

You are expressive. You make art.

Rejoice - you have become human.