I’m giving my talk on The Modern Resume – Building Your Brand a few more times this year and I’ve got a tentative schedule here:
June 6 – SQLSaturday #14, Pensacola, FL.
July 2 – Richmond SQL Server Users Group, Richmond, VA
Nov 11 (tentative) SQL Connections, Las Vegas, NV. I’ll be speaking at the event, just not sure of the day and time.
I’ve also submitted this for the PASS Community Summit, we’ll see if I get picked.
This is part one of a series on writing a technical article. The advice might apply to non-technical articles, but I’m focusing specifically with my examples on technical pieces. Other parts are listed at the end of this article.
I deal with a lot of first time authors, people that are working in a technical field and want to publish some type of article to share their knowledge or work. And I see all sorts of quality of articles from highly polished and ready to release to drafts that aren't as good a quality as my ten year old might write.
Even allowing for the language differences from around the globe (I get submissions from many countries), the quality of writing is appalling at times, and even when it's not poorly written, it's often not well structured.
The first thing that I'd really suggest for people is to pick a topic, or theme, for your article. Think about what you want to write about and then write an abstract or at least a topic sentence.
As you write, you should be able to go back to your topic sentence or your theme at any point, at any paragraph, and you should be supporting that theme. You can diverge in your writing to make a point, or give an example, but your writing should almost always be supporting your theme. If it isn't, you're off track.
Too often I find technical writers worrying about losing people, worried about covering their bases, and so they try to spell out every detail, or they include lots of background about lightly related subjects, or they want to be sure that someone implementing this technique understands everything needed for the entire infrastructure.
Don't do that.
Focus on your small topic. If you are teaching someone about encrypting data in SQL Server or in an ASP.NET web page, don't tell us about configuring IIS or creating server certificates in SQL Server. If that's needed, mention it, but don't go into details. Point people to another article, or just the vendor documentation. Or Google if you must. But write about the one small piece of technology you have chosen and leave other parts for another article.
Write about what you are teaching us, and assume people have some base level of knowledge. That might be a beginner in a topic, or an advanced used, but no matter which level you write for, you can still focus on your one area.
One thing I usually tell people is that a good technical article tends to be in the 2-5 page range (perhaps longer if you have lots of images or code), but beyond that you might want to consider splitting it into two parts.
Everything above is general advice for trying to determine what goes into the article, but how do you structure it? The "default" advice, the advice that I think everyone should follow until they're established and comfortable writing articles that someone else publishes, is this:
Or in other words, have an introduction, a detailed middle section, and then a conclusion. This is standard essay advice that most people get in grammar and high school, and it still applies for articles. Blogs can be different, but for an article, follow this advice.
The introduction should have your theme or topic sentence, and then some details that explain what you're showing, and perhaps some back story about how you discovered this, or how it fits into a common situation.
The details should be just that. Walk the user through your code, your settings, explaining things. You ought to be able to give the article to a non-technical, or low-technical user and they should be able to follow along. They might not understand, but they should be able to follow things.
I tend to advise people to show snippets of code and then explain them as they go rather then show a huge section of code at the beginning or end, but it can work either way. You can even make the code a download and reference sections or line numbers. If a technical person can't load code into an editor, they probably shouldn't be reading your article anyway.
For the conclusion, it feels silly, but summarize what you've said. Restating the theme does two things. One it reinforces things for the person reading. They'll agree that you've shown something and it will stick with them. Of course if you haven't done a good job, hopefully there's a feedback mechanism for you to find that out. The other thing is that in writing that conclusion, you should go back and think about what you've written up to that point. Does your conclusion really summarize things?
The conclusion for me also tends to include a teaser to another article, a way for the reader to move on, or perhaps a quick note about what (specifically) this technique has done for me.
The rest of the series on how to write a technical article.
One of the ways you can build your brand that I mention in the talk is through volunteering some of your time or skills to help others. There are a variety of ways you can do this. A few examples:
I'm sure you could find many more ways to help out, but I think these are the main ones I'd recommend for technical people.
Some people think that volunteering isn't a place where you should call attention to yourself, or that you aren't being humble by doing so. My advice along these lines is as follows:
First, don't volunteer unless you really want to help someone. In other words, have a good moral reason for helping out and be comfortable if you don't get any recognition.
Second, don't call attention to this in general. Mentioning it on your blog is OK, but don't make a big deal out of it. If you learned something, or grew through the experience, talk about those things, don't talk about the volunteering part of it.
The exception I'd make here is if you are trying to get others to join you. Then it makes sense to promote the efforts.
Lastly, your resume (or CV, or in an interview) is the place to talk about things you do. This is the time you can promote yourself, and volunteer efforts enrich you.
They also take away your time, so if you want to continue, and if you did it for the right reasons you should, make sure your potential new boss is aware of this.
I have a few presentations of The Modern Resume scheduled for the remainder of this year. If you're in the area, feel free to stop by.
I am still trying to figure out if I'll get to Utah. There are two groups in the Salt Lake City area that have asked me to come. We'll see.
