Creating compelling content

Lorna: Hi, I'm Lorna. I'm a developer advocate for IBM. I'm relatively new in this role. Before that I was a developer. I think I'm an engineer that just kind of fell over and writes more words. Now as a background, I'm also a published author. I've been a blogger for 10 years. I'm published by other people as well as by myself on Lean Pub because that was fun, but I've been keeping a blog for a long time and I think that written content is really, really important and I'm going to talk a little bit about why I think it's magical and also all about my process.

Some advice because I think as advocates, in order to reach a lot of people, we all need to write and maybe some of you don't love it quite the way that I do.

When you write something down, you're solving a very specific problem, and that problem is there's something in your brain that you would like to give to somebody else's brain, so you have a few options on how to achieve this. First of all, you can just show them so you can sit down and you can tell that person that thing, and I think I'm generalising obviously, but as advocates, we tend to be pretty helpful people, right? We like to help people and we're always happy to do this. If you ask me something that I know, I will always sit down and I'll tell you about it or try and show you to scale this up. Maybe we could let some other people listen. Perhaps I show you something and a little crowd gathers round and now there's four or five people. If I'm running a training course and I'm fixing a problem for one person, maybe I'll plug it in the projector so everyone can see, and that scales it up.

When you write down that thing that's in your brain, it transcends space and time. The person whose brain needs this doesn't need to get to know you, doesn't need to be in the same place as you. Doesn't need to realise that you are the person that knows that they should ask about this thing. When you write it down, you can reach everybody everywhere in the world. They just need an internet connection, and it can be something which they can come along a couple of years later needing to know this thing that you knew and now it's gone. I used to be a subversion power user. Wow, that's gone. Someone asked me a question recently and I was like, just need to look it up on the blog.

I'm sorry there's nothing left. So it gives us this absolute root of sharing right across all of the possible boundaries. I think this is so, so powerful, not just about saving airfare and jet lag and all those things, but also about really reaching across boundaries and being able to open up communities and individuals anywhere.

When I talk about writing, particularly people from a technical background tend to tell me they dunno what to write about. Well, if the a, b, C of being a digital nomad is, you should always be charging, see a PowerPoint, plug something in all the time, always be charging. Then the A, b, C of writing is to always be capturing ideas. Just keep a list somewhere, a list of draughts in your WordPress blog, I use literally my to-do list with a category for things I might blog one day and some of this stuff you will throw away. Some of these ideas are genuinely bad or more tweet sized than blog posts sized. Some of them are magazine article sized or might even be book sized and sometimes it's hard to tell, but if you don't capture those ideas, you'll always suffer from this blank page mentality. Our best ideas happen often when we mix with others. We're at events, we're giving a talk tomorrow there's a demo to write.

Everything's chaos. Capture that idea, put it somewhere safe because the probability of having the idea the same day that you've got a spare half day to write a good blog post is otherwise nil. Try and make these two things crossover.

Some people tell me their ideas aren't good enough, and for inspiration, I turned to my own blog. This might be a bit tiny to read, but this is a list of the most popular articles on lorna jane.net over the last 30 days for whenever I made these slides. So two or three weeks ago, you'll notice that the most popular article here is about how to post JSO with PHP groundbreaking, no world changing, no, but hopefully it changed somebody's world and it seems like I'm helping a bunch of people. Number three is three ways to make a Post Request from PHP, which is equally riveting and ironically, none of those three ways are how I would actually make a post request from PHP today.

There's lots of things here which have helped a lot of people. You can see my clear PhD background, but how to SQL join a table to itself? Some people don't know that I can write it down and everybody who needs to know can find it, so don't think that you need to be super original or innovative or really groundbreaking. The world doesn't necessarily need more rocket science. It needs more sensible advice from people who are ahead on the path than the people behind them. Before you begin, you need to do a little bit of planning As developers, if any of you have done hackathons, which I'm guessing you may have done, you've seen this, people have a great idea and they immediately start writing the code, and as developers, this is a disorder that we all struggle to overcome when it comes to writing any kind of content, you cannot just jump into the words.

Do not jump straight in, do not pass, go. Do not collect 200 pounds. Just don't do anything until you've really thought about what you're doing. The net time to successful delivery of something useful is massively reduced if you stop before you start. I'm making sense honestly. So some important questions that you must answer before you write anything. Who is this for and what are you giving them? Think about who will read this, what is their context?

I used to develop software for HR departments, and so we had a mystery customer who we called Doris and mostly because none of our customers were called Doris, so that was helpful. So Doris is at the top of her game, loads of qualifications in the area of hr, very experienced, has been promoted, probably doesn't know how to work her computer, and so thinking about that sort of disconnect between I write software and I need you to be able to use this technical tool versus this person actually is an expert in some other discipline. That's important context, so it's about what do they know technically what tools are accessible to them. I'm a Vim user, but I try not to cloud what I'm doing with that because it's not for everybody and it's not terribly accessible for someone who hasn't seen the tool before.

It is a little bit about cultural context as well. It's a little bit about which tech community do you come from geographically, where do you come from, which year were you born in? What's your cultural references? We tend to think that everybody is into a lot of the same cultural things, but that's not true. Your Star Trek, star Wars, Stargate, whichever one of those things, I haven't seen any of them, so you can use them as an analogy if you like, but you need to introduce this captain of the Starship thing and tell me why he's important, and if you are comparing him with another character to make a point, then you need to introduce that person too and tell me something about him. Otherwise it's lost. The context is really important. It's also really important that you think about what the outcome is.

Just because a tool is cool, you want to write about it, that's nice, but what are you giving to the person who reads this? What will they be able to go home and do? What are you aiming for them? When I write a workshop, I start with the learning objectives and I don't think it's too grand an idea to apply the same thing to our writing. Your introduction could always say by the end of this article, you will be able to build your own plugin for the Amazon Alexa thing. Awesome. Okay, now I know where I'm going and I can start.

Structure is super important. You need an outline. I have stolen this one from a recent blog post that I wrote on the work blog. It's about using MQ from an existing PHP application. So the outline introduces the application, configures rabbit MQ puts from PHP messages onto rabbit MQ talks a bit about where the message goes, what you should do next, and then gives you a big fact call to action. Go forth and use rabbit MQ in your PHP applications and that's a structure so you can write this and think about how you want to lead this user through this process that you are hoping they'll follow some sample code. The other thing that I love about outlines, it means that when you drill down into the words, you don't lose your way. Also, if you are at lots of events and you're writing blog posts in half hour blocks at airports or on trains or all those other little bits and pieces that we sometimes find ourselves doing, this structure is cool.

You can write a section in one place and then write the next section and have a sense of what you've already covered. There are a couple of things that I think it's quite important to avoid. Let's call those antipas. One of those is the preamble AntiPattern. Try to avoid giving readers a huge amount of history or backstory or background information before they get to anything interesting. They can't remember it all and they've lost it. If they genuinely need some extra context, try and just feed it in as you need it. Try not to lead with a lot of backstory.

I feel this way about talks as well. The ones that give me three slides of history of a thing can sometimes be a bit, could look this up on Wikipedia. The other Andy Patten that I'm probably guilty of, but now I see all the time is that what I call the garden path anti-pattern, where you show someone how to do a thing and then you tell them that's terrible and you show them how to do it better.

Longer form writing does this, so books often do this. The user that just followed you down the path, followed your instructions and now built a thing, you just told them it was terrible, they're not going to keep reading. There are people who don't keep reading anyway because they've achieved what they wanted and then there are people that you just insult. So try and even if you are starting from one place and showing how it could be done better try to go just to a positive outcome. Lead the user where they eventually want to go. Try not to deviate on the way there. Once you've got your outline, you have a plan, there's a plan. This is where it gets hard.

You need to write the words. Just show up and write the words, and if you are not a natural writer, this is hard and there isn't a way of saying anything other than this is hard.

Yes, this is hard. I am a very well-educated native English speaker. I have all of the advantages in the world and some days this is hard. I've written books and some days this is hard. You turn the handle and a few more words drop out and sometimes you have to turn the handle quite hard to make the words drop out. It's not about sitting there until inspiration strikes. You communicate for a living, right? DevRel is about spreading the word.

You need to show up and you need to write the words, and I don't have a good kind of tactic for sugarcoating this and telling you it's going to be great. Sometimes you just need to show up. Try not to worry about any other stuff. Don't censor or edit as you go. Don't count the words. You should have slightly too many anyway. Just run with it and see where you get to try to keep it varied.

It's very important to break up a lot of written text, especially we have this blog theme at work, which is about this wide, so you only need to write about five sentences. You've made this wall of text and that's very common. People can be reading on different devices which has the same effect, so it's about avoiding a wall of text, but it's also about giving users some landmarks, some furniture, so if they need to look back at something, they can kind of find their way around the shape of the piece. Subheadings are essential, code is great, lists are helpful. Any kind of, don't be afraid of tables or particularly pictures. A flow diagram can go so far for a reader who isn't already familiar with the topic that you are covering.

Lists are cool, but only if they're actually a list of items. If this was a list of the things you wanted to say and you don't do sentences right when you edit, go back and put sentences around them and just take all the bullet points out, turn them into a paragraph. It typically works, so try to break it up a bit. It helps make your content more digestible because we want the user to be able to absorb it as easily as possible. We want them to get all the way to the end. Sometimes you can feel like you're waffling. You probably are in the writing the words stage. Just write the words, but then come back and be merciless.

If you're lucky, you work with content people that can help you to kind of whittle down some of the words, but if you are editing for yourself, then you need to try and do this yourself. Take a sharp implement and take out every sentence that you could manage without. Take all of the prevaricating extra phrases and long ways of saying things out because to keep your content simple, makes the best use of people's time is respectful. It also makes your content accessible to more people so more people can follow it. I'm capable of very flowery English and I try not to, particularly for a technical article because I think it increases my readership if I can keep that just very clean and as simple as it can be.

A lot of writing has requirements around word count, and this is just a thing that makes no sense until you've written so much that you can't help but understand it. Word counts, measure how big something is, how heavy something is. If you tell me that you've written 500 words on something, I have a sense of how deep you went into that process. The only time it really matters is for print. The page is only so big, the editors know how many words they can get on that page, right? Then your word count really does matter and people will get really upset if it's wrong. Trust me, that happens.

If you write too many words, nobody will read them. That sounds really harsh, but it's true. Nobody that I'm aware of is publishing anything longer than 3000 words and many outlets no longer publishing 3000 words, particularly on the internet in a digital format. It's hard for us to read. Sometimes you may find it appropriate to break things down into a series or maybe refer out to some stuff to write a separate installing, getting started tutorial or go and improve the readme so you don't need it all in your tutorial, and that can sometimes help to move the content around and keep your post whatever you are working on. Really, really focused.

One thing which is really hard is asking for criticism and yeah, I struggle with this, but the thing about having reviews before you publish is that you're making a fool of yourself for a much, much smaller audience, so it's always, always worth it. I was a little bit controversial on the internet this week and I'm one of the advent posts and yeah, that went to a couple of people before I submitted that content and we did make changes. Yes, we did, and I'm quite glad that we didn't publish the original version. This stuff is difficult and if anyone's prepared to read what you've written, bite their handoff, particularly if I have a team of content people whose job it is to make me sound like a reasonable and sane human on the internet, and they do a pretty good job at that. They also Americanize all my spellings.

I mean, it's not like the spelling is their main value, but they're very good at that too, but I think if you don't have that, you need to find it or make it. This is like having a support network. If you don't have a support network, you need to find it or make it, and maybe we are finding our support networks today because I know a lot of us work alone or at least travel alone a lot of the time, so people who are prepared to review and offer you feedback are very valuable and you can ignore their advice if you want from time to time, but it will always improve you and it's always, always valuable.

I love to write, I have always loved to write, and who knew that developers were even allowed to write words? I love to have a job that combines the two. Maybe you don't love to write. Maybe you're expected to deliver blog posts and you don't have an affinity with this. That's okay. Yeah, I'm not asking you to love it, but hopefully some stuff that I've shared here gives you some tools, some ideas of why I think it's important, but also some tactics to actually make this happen because if you're not loving it, it is hard. I definitely got better at it. I might be a O'Reilly author now, but you can go and read the 2006 posts from Lorna jane.

net if you want to see how far I've come. They were terrible, and you can't begin to improve until you begin. So when it comes to write words, I've tried to give you a process. Think about the ideas. Make sure you genuinely know who you are writing for and why they would want to read it. You might want to write it. That's nice. What will they take away from it?

Think about the structure and then just show up and write the words. That's the end of the advice from me. Thanks very much.