Get a second opinion on your blog

In addition to blogging regularly, learning about new things, and learning to edit your work, it’s important that you also present your knowledge, skills, and efforts in a positive light. All too often I find people that write technical articles understand what they are writing about, and are very knowledgeable, but are unable to communicate well.

Editing is important, you can certainly learn to spell correctly, catch typos (their v there) and fix grammar issues, but are you actually, logically, explaining what you have learned or accomplished?

It’s hard for most of us to play the part of the teacher and student when we blog. It’s too easy for us to assume the student will understand what we mean, without realizing we are assuming too much knowledge. It’s also too easy for us to skip logical steps because we think everyone would automatically realize they were implied.

Do yourself a favor when you are blogging and get second opinions from friends or family on what you writing. Ask if your posts read well, and if they make sense. Even if you have someone that doesn’t understand the topic read the article, it should flow and be easy to read. If it’s not, fix it before you publish it.

This is your brand and it’s just as important that you present it positively as it is you keep adding to the knowledge in your field.

Better Writing from Hemingway

These are five rules for writing from Ernest Hemingway, which I like and recommend for use in your communications. Definitely try to incorporate them into your writing, especially being short and positive.

Tips for Speaking

I've read a few books on speaking, and looked to get feedback from people on what I can do better in my talks. I've learned things, and I think I've improved over time, but there are always ways to get better. I've considered Toastmasters, but time is precious for me right now and that's a night that I can't spare in the coming months. However I do want to get there at some point and have some practice talks.

Recently I saw a great post at The Goal Keeping DBA, from Brian Kelley called Tip on Speaking (and Writing) Well – The Key Idea. It's actually based on a Toastmasters article that Brian has distilled down. He has some great advice on speaking, or writing, and it's worth reading.

It's also similar to the advice I often give authors as an editor. Focus on something and do that well.

Express Yourself Clearly

Recently my son had a short paper to write for school. He’s a sixth grader, and this year is a turning point for him where he’s expected to think a little more about his writing as well as tackle longer assignments. In this case it was a 2 page paper on Sophocles, and he was struggling one night with the paper due the next day.

Before you say that he should succeed or fail on his own, I agree with you. However as a parent, or manager/mentor/helper, you pick and choose those places where you provide assistance, and to what level. In this case he’s had a major change in his life with sixth grade and the beginning of Boy Scouts. While this doesn’t matter for college in terms of his grade, it is the place where he is gaining a base of learning, and I think it’s the time where I provide more assistance than I might otherwise provide.

Next year will be a different story. I’ll let him struggle, and potentially mis assignments if he doesn’t manage his workload. But I digress.

The issues that he had with producing a coherent paper that explains his thoughts while presenting information were similar issues that I see from many of my authors at work. The issues are also similar issues that I see in many blogs. While I’m not a top-notch writer, and I take liberties at times in blogs and editorials, I tend to see a few common mistakes in a lot of pieces that people write.

Don’t use pronouns

That was the main advice to my son as we worked through his paper. He, and many others, tend to use pronouns (“it”, “his” and “they” especially) to convey their thoughts. However they often have not tied the pronoun to a specific noun and the reference in ambiguous.

Most people learn this in grammar school, but they seem to forget it when there’s no grade attached to their work. As an example:

Sophocles was a great writer. He often worked with Aeschylus and his plays were similar.

What does “his” refer to? Is it Sophocles or Aeschylus? Either could be the reference and the reader has to take a guess. It’s possible that context before or after this sentence will help you to understand the reference, but it’s equally likely that you will mis-interpret what is intended.

This same type of ambiguous reference occurs in many technical articles, often when someone is trying to compare two items and show how they work in a similar manner. I correct this type of reference constantly, and often ask for clarification from authors.

So my advice is…..don’t use pronouns.

If you can avoid one, avoid it. Repeat the noun and make it clear. This does two things. One it helps the reader to better understand your meaning, but it also forces you to be more specific.

Writing Technical Articles - A Few Simple Tips

A few simple tips that I've learned over the years. Keep these in mind as you write your next article.

That and Which - It's amazing how often I correct this in writing, and it was something I learned early on. If you use "that" in a sentence, you don't need a comma. If you use "which", you do. A few samples:

• The DMVs are system views that allow you to gain insight into the server operation.
• The DMVs are views, which give you insight into the server operation.

There are a few other rules here as well. That should be used for essential clauses, meaning the are necessary in the way things are worded. If you have non-essential clauses, like descriptive information, use "which."

If you use "that" in one sentence, or earlier in the paragraph, you can switch over and use "which" for the sake of better flow.

Its vs. it's - I still mess this one up at times, but here is an easy way to read your sentences and avoid mistakes. Replace "its" with "it is" when reading. If it makes sense, you're supposed to be using the contraction "it's" and not "its." If it doesn't make sense, as in it's possessive, then stick with "its."

• I have found it's important to test the boundary cases. (Test: I have found it is important to test the boundary cases)
• In this particular boundary case, its result is zero. (Test: In this particular boundary case, it is result is zero. Doesn't make sense. stick with "its")

Capitalization - Surprisingly this is more difficult than it seems. Proper nouns and names are capitalized, and of course, the first word in a sentence. Outside of that, don't capitalize random words. So SQL Server is the proper name of a product, but "the database server" is a generic. Don't capitalize "Database Server," which is something I see often. The same thing applies for groups, even if you think they're specific. I realize you are talking about your "development team" or your "manager", but unless you call them out by name, or you are using the title of the group, they aren't capitalized.

If you've got questions, post them in a comment and I'll try to answer them. I'd also recommend that if you want to write, pick up a style guide. Microsoft has published a technical one and the Chicago Manual of Style is always a good book to keep around.

The best advice I can give you is to have someone else look over your article. I realize that I don't always do that for my editorials, and some of that is because of the time pressures and crunches I get under to get things done, but for technical articles, I'd be sure that you have a friend read it.

Better Blogging

I'm not sure I agree completely with Brent Ozar's advice at Building Your Blogging Momentum, but I like most of it. It seems aimed more for someone looking to raise their profile and not necessarily the average guy, but that's OK. There are lots of people that want an MVP or want to become more well known.

It's what I talk about. Building your brand and making a case for why you're a better employee. Blogging is a great way to do it, and while I know not everyone is a writer, in the IT world, we all need to communicate. Blogging is a good way to build that skill.

And show what you're working on, learning, etc.

Am I a bad employee if I don't blog?

No.

Blogging is not for everyone and you don't want to give the impression you are something you are not doing something right if you don't blog. Not everyone is a writer, not everyone likes putting their thoughts down, and not everyone is brave enough to publish out on the Internet.

It takes a thick skin, and even after doing this for years, I still get attacked regularly, and I don't always take it well. I'll admit it gets to me. Luckily I have a good support system with my wife and friends that can pick me up when I've had a particularly nasty comment.

I do a presentation on The Modern Resume, telling people how to big a more noticeable presence in the world, making yourself stand out more. I think blogging is the easy way to do this, but there are others:

• Volunteer your time - Answer questions online, help out a non-profit group, or something like this.
• Lead or manage - at your company, mentor someone, work with a church or other community group
• Do your own research - Learn how to do something, and then show your boss or a prospective employer.

I don't think you can get away from writing completely since you'll need to document and explain things you've done. However it can be as simple as notes you've made to yourself and a few lines on your resume or CV.

Writing is a skill, however, and I'd encourage you to develop it. If you don't want to blog, it still makes sense to pay attention to how you communicate in email, in reports, and in documentation. Learn to do it better and your career will benefit.

Writing Technical Articles - Finding Ideas

This is part two 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've been asked often about where I get ideas from. The answer, for me, is everywhere. Every conversation, email, article, almost everything that happens in my life triggers thoughts and ideas, and as a writer, I tend to think about how I would write about things.

That took years of practice, and constant writing to develop that skill, but I've heard similar things from people that don't write daily like I do. However I do have a few ideas and thoughts.

First, anything that you do in your job can be an article. Any problem you solve, any solution you implement, they can be an article. No matter what you're working on, I can likely find a way to write it into a technical article.

Second, remember that you are teaching someone about the technology. You want to consider how you would mentor someone else about this technique. If it's anything non-trivial for a layman in your area, it can be written about.

I tend to focus more on beginner articles, and I think that's a good place for new writers to consider. Different publishers will be looking for different levels of content at any time, and they'll often let you know if your article doesn't meet their needs.

As an example, here are a few things that I've seen happen in my environments and then written about:

• Exceeding the size of a INT in an identity column from over 4B inserts.
• Moving tempdb
• Template use in Query Analyzer
• Routing issues when multi-homing a SQL Server
• Designing a simple database for a specific type of content.

Some of these are beginner, some of them are more experienced, but the topic doesn't matter. Different publishers will have different criteria for what they will publish.  They will let you know, and you can work on your article based on where you will publish. SQLServerCentral will publish almost anything while MSDN will be very choosy about which topics they release.

Any problem that you have solved is likely something that plenty of other people have not. And the longer you worked on it, the less information you found on it, the more likely it's a good candidate.

The one thing I caution people against is writing general overviews. Too many people write these, and they often don't add information or knowledge to the world. We each have our own voice, but overviews are so generic that you likely won't reach different people with yours. Instead focus on a specific area and give details. Your readership will appreciate it.

Writing a Technical Article Series

The rest of the series on how to write a technical article.

• Part 1 – Structuring Your Article
• Part 2 – Finding Ideas
• Part 3 - Where to Publish

Writing a Technical Article - Structuring Your Article

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.

Pick a Theme

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.

Focus, Focus, Focus

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.

Tell Me, Show Me, Tell Me

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:

• tell me what you are going to write about
• show me what you told me
• tell me at the end what you told me

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.

Writing a Technical Article Series

The rest of the series on how to write a technical article.

• Part 1 – Structuring Your Article
• Part 2 – Finding Ideas
• Part 3 - Where to Publish

Authoring an Article

If you are comfortable blogging and writing for yourself, and you have a thick enough skin to consider putting your work forward, the next step I'd recommend is writing an article. If you aren't blogging, I'd recommend that you start there, get comfortable with writing and expressing yourself and get practice. Writing is a skill like anything else and practice makes it better.

Many online publishers are constantly looking for content and often entertain short pieces from new authors. In the technical world, there is no shortage of sites that cater to your particular specialty. In other fields, there are likely just as many choices.

In trying to structure an article, the first thing to keep in mind is that when you move away from a blog-type structure to an article is that now you are definitely trying to teach your readers something. The premise in writing your article must be that you are conveying information, teaching a subject at some level.

I have more detailed post coming with specific advice for technical articles in the next few weeks.

Branding on ESPN

I was listening to Colin Cowherd and the Herd one morning and he was talking about the Los Angeles Dodgers and Manny Rodriguez. At first I wasn’t sure I agreed with him that the Dodgers should spend $25million to sign him. Is he worth it? Does he make a difference?

Then Colin stepped back and started talking about branding, and that got me interested. Twenty years ago the big stories in sports included the Yankees and Dodgers. I’d agree with that as the history from Jackie Robinson through Bob Gibson, Sandy Koufax, Tommy Lasorda, I remember hearing about them in the 80s, seeing them on Sportcenter regularly, and knowing that the Dodgers mattered in sports. They actually seemed to be more people around the country supporting the boys in “Dodger Blue” than even the Cubs.

However I agree that’s changed. Nowadays the Dodgers don’t make as big a splash, and they’re not featured in highlights that often. The exception was last year when Manny was traded over there and hit home runs. All of a sudden they caught my attention slightly more.

That’s branding.

Colin brought up an interesting point. ESPN shows highlights and lead stories, which are often a minute or two long. If you could get yourself, or your tem into those leads, the A blocks, you are building a good brand. Buying a 30 sec ad for the season would cost millions. I’m not sure if it would be the $25mm Colin mentioned, but it would be something. If you could get Manny to advertise you more, as a side effect of his signing, in addition to more seats, (likely) more TV coverage of games, and apparel, he really could pay for himself.

As much as I hate to admit it, he might be the top name in baseball.

So what does this have to do with your brand? How can the individual DBA benefit here?

You have a brand as well, and it be used to promote yourself. You won’t get a $25mm contract, but you can leverage yourself in other ways. In the grand scheme of the world, Manny is small. Just as in the scheme of DBAs, most of us are pretty small.

You can get more exposure, grow your brand, and get a level of networking with one simple thing:

Write an article.

It can be intimidating, and it’s work. But it’s an investment in your career that is worth making. I don’t want to exclusively promote my site, SQLServerCentral, but I will say that you’ll likely get the most exposure (500k+ newsletters sent out) for your work with the least effort. I’m an easy editor, and we don’t require huge amounts of research. However there are plenty of other places (SQL Team, Database Journal, MSSQLTips, etc.) that you can write for in the database space. In other technologies, I’m sure you have favorite sites that you visit.

The thing to keep in mind is that this effort, your first article, is going to showcase your brand. Spend some time on it, get friends to review it, and teach the world something. It doesn’t have to be earth-shattering or amazingly innovative. However it should be in your area of expertise, whether that’s writing SQL, managing security, grooming a dog, or training a horse. Write something well that shows:

• your knowledge
• your communication skills (present the ideas well)
• your attention to detail (watch the typos/spelling/grammar)

And then make sure it’s on your resume. I bet it gets mentioned in your next interview.