As a development community we’re better together. We learn more, we build more awesome things and we’re happier. Blogs and Q&A sites like stackoverflow highlight the growing trend of self-taught programmers learning from the internet, rather than from schools or universities. This isn’t new, programmers have been self-learning for decades - but it used to be from books rather than things written by their peers in blogs and forums.

There are plenty of people who are interested in writing about their experiences - but putting yourself out there and actually doing it can be intimidating. It’s easy to think that you don’t have the skills to articulate your opinion or that you can’t write.

The barriers are real - so lets talk about them…

 

I’m scared of writing!

Writing is like any skill - it takes practise and discipline, and you’re probably not going to be amazing at it straight away. For the vast majority of people, being scared of writing is actually just the fear of sounding stupid - perhaps you don’t think your opinion on something counts, or that there are other smarter people talking about the same sort of things that you’re working on.

The truth is that you will only ever get better at anything by doing it. If a single person benefits from reading about your experiences, you’ve changed the community for the better. There will always be somebody smarter or more knowledgeable than you. If they disagree with what you say and respond to what you write, you learn how to be better - if they don’t, you help others learn.

You will get better - and the best way to get better is to write regularly. If you’re committed to improving, writing every day will help a lot, but practically, once a week is probably enough. When writing about tech, there are lots of small things worth sharing - so write about those, keep it short, and practise.

 

But I can’t write! How do I get started?

There are some easy tricks to get started - remember high school essay-writing? It’s a lot like that. People aren’t going to be interested in what you have to say by default, so you need to hook them and sell them with your title and first paragraph. This is more important in technical writing than other pieces because your reader is often looking for something specific, and you have to give them the impression that you’re dealing with the topics they’re looking for.

When I started high school I had a teacher who described writing essays as

“Tell them what you’re going to tell them.  Tell them.  Tell them what you told them.”

...this stuck with me, and it’s a useful structure to follow if you feel like you don’t know how to get started. You open with the hook, follow with the detail, and then close with the key learnings. It’s helpful to outline these sections of your piece as bullet points and then expand them into prose - rather than “just writing”, just like an essay plan in school.

Once you’ve nailed the core of your topic, read it twice and edit it down, cutting out complex or inaccessible language, explaining any jargon and removing filler words. This’ll make sure that what you’ve written is tight and to the point.

 

Telling stories

The purpose of most technical writing is to educate, but good writing informs and entertains. You need to learn how to strike this balance to make what you’re saying easy to follow and engaging. If you look at some of the most popular technical writers over the last decade, many of their most pieces are entertainment with education adding substance. Jeff Atwood and Joel Spolsky are both tell stories while talking about technical things. Stories help the writers establish their voice - making it more likely that readers will return and read subsequent pieces based on the “way they tell them”, regardless of topic.

With those authors, the stories that surround their technical posts are “framing devices” that help readers relate to the topic, sometimes taking the form of allegories to hook the reader. They’re used as introductions and foreshadow the technical parts of their articles, giving them context and motivation.

Contextualising with stories makes the concepts in their writing relatable to people who haven’t been exposed to the exact scenario they’re describing, but may have experienced something similar - helping the reader understand how they can apply or better understand the topic.

Framing your writing with stories helps people connect with what you’re writing, and it’s prevalence in the best technical writing helps offset some of the dryness that plagues most technical documentation.

 

But this is technology, it’s inherently dry and complex!

Just because technology is detailed and tightly articulated, it doesn’t mean that writing about it has to be dry. You’re not writing xmldoc/javadoc documentation, you’re writing content that people need to comprehend and understand - and there’s talent in distilling complex topics and dealing with them plainly. It’s easy for developers to fall back to “just pasting the code into a blog post and expecting someone to read it”, but people are unlikely to read through it.

Technology is complex, though, and if you’re writing things that deep-dive into complex topics, you’ll likely be writing for a specific and skilled audience. Don’t make the mistake in thinking that because your audience is proficient, they won’t appreciate well-articulated guidance.

Jon Skeet’s blog is a great example of writing that edges towards “posting pages of code” while still engaging the reader with narrative. Jon posts snippets of code, building up to larger complete examples - it’s literally “textbook style”, where small pieces of information, narrated and explained, are eventually combined together to form a whole example. This is the correct way to help people work through a detailed code sample, only hitting readers with “the big wall of text” at the end, when they’re equipped to understand it.

Anyone who already understands all the text above it will happily scroll past the explanation looking for the GitHub link - letting you serve both audiences.

 

Layout and formatting

Layout and formatting is a discipline to learn, and can be easier to pick up than the softer narrative skills. Formatting and layout help keep your writing scannable, which is especially important when you’re writing for the web, where people tend to scan content before committing to reading it.

There are a few tricks you can use to help people read your work;

• Splitting your piece into headed sections with subheadings helps readers “get the gist”
• Lists can be useful to guide a reader through specific advice (meta!)
• Images or illustrations help break up longer pieces and can help grab attention
• Highlighting important phrases with bold or italics helps people skimread
• When writing for the web, use links to good further resources where applicable

If you’re trying to build a relationship with an audience, chunking longer posts into series can encourage repeat readers - it’s a good way to keep the momentum going when you’re just starting up, but beware starting something that you don’t intend to finish, as it’ll only antagonise your audience. If you’re going to “do a series”, cut a longer piece, rather than writing them piecemeal.

In general, highlight important content, and break up large amounts of text with paragraphs, images, and sub-headings. These splits should be informed by the outline of the piece that you started with, and should be natural, and you’ll get better at them over time.

 

Things to avoid

There are a handful of things that’ll put people off reading very quickly:

“The big wall of text” - characterised by a complete lack of formatting or flow. Pieces written without attention to layout put people off because of they can’t be scanned easily. The longer they get without attention to form, the less likely people are to read them.

“The business domain guy” - people are looking for lessons and flavour from your experiences, they don’t want to learn your entire business domain to understand the concepts you’re trying to explain. As a guideline, if you wouldn’t care to know it about somebody else's business, they don’t want to know it about yours. If you’re using examples, it’s better to genericise them than to place the burden of understanding on the reader from the start - just explain how the example relates to your specific problem domain briefly.

“The nerd-rager” - as a simple guide, don’t loudly complain about anything that you don’t intend on suggesting a solution to - no good comes of angry people on the internet, so make sure you’re offering productive and constructive criticism rather than raging.

“The rambler” - normally the result of not re-reading the piece and subbing it when you’ve done. Resist the urge to just publish what you’ve written without cutting it down, because there will always be something you can cut.

“The giant code sample” - GitHub or BitBucket (oh okay, or SourceForge) are the places for enormous, stand-alone code samples - link to them and resist the urge to post huge code samples without narration.

Steer clear of those archetypes, and you’ll be safe.

 

Wow, it’s *just* that easy?

There’s a lot of detail here, but the most important thing to remember is to avoid analysis paralysis while trying to find the next big thing to write about - just share what you know or what you’re learning and get started. You won’t be the best writer overnight and you’re not just going to stumble into your voice and find a great audience.

If you’re blogging, you’ll want to make sure you share what your write - at least on Twitter and Facebook - and perhaps with the more contentious audiences on Hacker News and reddit. You’ll get feedback, maybe sometimes negative, but don’t let it discourage you.

As a technical community, we need people to share what they know, and the absolute worst thing that will happen is that nobody will read what you publish - so don’t worry, everyone starts somewhere.

 

Slides: