Christian Heilmann

Posts Tagged ‘writing’

Check the source before you tweet

Friday, December 16th, 2011

Working for a large entity of the web is an awesome thing. You have access to great people, resources and you don’t have to chase the next paycheck or prepare the next pitch document to boot. The thing that can make it taxing – if you let it get to you – is that everybody and their dog has to say something about your employer. These things mostly fall into a few categories:

  • The “company XYZ should do this to be successful (and/or survive)” post. I like these, they normally come from people as far removed from the entity as possible. In most cases, they aren’t even working for other companies or as business consultants. Which is a shame, really, as when they know so many amazing simple things to bring success then they should bring it to where people implement it, right?
  • The “I used to use XYZ but I like ABC now” post. Good for you, if you are happy, I am happy
  • The “OMG did you read this about your company” tweet

The latter is what I want to talk about a bit.

Why repeat the report?

The most annoying blog posts, tweets and other “social media” releases are re-hashing what a certain tech media outlet has said. In some cases, even taken out of context, boiled down to the most shocking or “amazing thing”. The fallacy there is that you are not telling the world what you are outraged about or interested in – all you do is bring the tech media outlet you got the message from money as visits are clicks and clicks are money.

Mike Butcher of TechCrunch gave a very honest and open talk about this lately which didn’t come as a surprise to me but should be something to take into consideration when you give a certain article your name and stamp of approval by retweeting it:

How to deal with tech media by @mikebutcher

View more presentations from mikebutcher

TL;DR: every piece on a tech blog is there to bring readers to the blog. It is not about the content – it is about getting the headline and being the first to talk about it.

I worked as a news journalist and this is really what it boiled down to: you have to be the first to have the info and when your media outlet is dependent on numbers you have to spice it up until it really gets people excited. If that means bending the truth or making wild accusations without backup, so be it. You can always apologise later. You will be washed clean but the original rumour will still bring people to your site. You win. You get paid.

Use the source

As web developers, view-source always has been our friend. It is great for debugging and it is great for looking beyond the shiny. You should apply the same to news reports on the web:

  • If there is a certain news about a company, check the official press release for comparison. If the thing the hoo-hah is about is real then there is one.
  • If the article talks about a source, go to that source and tweet about that one. In many cases, this is better quality. A good example just happened: A friend of mine, Dennis Lembree, tweeted about a the best places to work report on TechCrunch and complained about it being inaccessible (as the data was an image with no text alternative). Looking at the news piece I found the source article on which is in HTML
  • Check where the source is coming from. There is no point in debugging the generated HTML when it is assembled somewhere else. If the person making a certain assumption about a company has no clue about the subject matter why give them the satisfaction to repeat what he/she said? Asking the wrong person for a comment is never a good plan, much like asking an unfunny car tester to give a quote about union matters can cause controversy

Don’t mistake SEO for the real thing

A post that really got me lately was 21 Types Of Social Content To Boost Your SEO linked here with the keyword horse manure (to see what that does to their Google rank). Whilst probably well-intended I was really annoyed by the tips given there to get eyeballs to your site. The ideas to get more people to your site – regardless of your content – are to use a lot of techniques, the ones that got me annoyed were the following:

1.) The Manifesto
The Manifesto is the viral equivalent of preaching to the choir. Write a passionate, eloquent, or well-researched argument that your niche will wholeheartedly agree with. Since you’ve already got an army of believers who agree with you, they’re already primed and ready to share your argument.
Example: Why I’m a Vegetarian, Dammit, an essay on a vegetarian recipe blog, received over 14,000 shares on StumbleUpon alone

Yes, that is because a manifesto is something you should believe in – by definition.

2.) The Controversy
The opposite of the Manifesto, the Controversy is all about stirring up some dissent in your niche. Write a well-written rebuttal to another argument, challenge a popular opinion, or spark a controversial discussion and watch the reader comments fly.

Translation: your readers are idiots who need to be lead into shouting at each other. Be the puppet master. Sensible discussion is for hippies.

5.) The Epic
Why do a top 10 list when you can do a top 100? Go for gold and craft a mega-list relevant to your industry. Examples of epic titles include “50 Must-Have Firefox Add-ons,” or “101 Tips for Increasing Productivity.”

Yes, cause reading 101 tips will totally increase your productivity. And the more add-ons, the better. Then you can also complain when your browser is sluggish.

8.) The Directory
Why make readers sift through mounds of data when you can do it for them? Collect the best links from around the internet and share them with your readers. Gather the best advice for your niche, the top news stories, the leading Twitter accounts in your field, or a simple collection of interesting information.

Remember, kids, this is how Yahoo started and see where they are now! Also, social bookmarking sites do not exist, your blog should do this!

11.) The Expert
In viral content and in life, it’s not what you know, but who you know. Name recognition is a powerful thing. When Mark Zuckerberg talks about Facebook or Mario Batali talks about food, people listen. For even more viral impact, gather a group of experts: “15 Published Authors on Writing,” for example.

My proposal “10 martial arts tricks Douglas Crockford never gave out before” (who the heck is Mario Batali?)

13.) The Visual Aid
Visual representations of mass amounts of data are easy-to-digest while still containing a lot of “meaty” content. Infographics aren’t the only example of this—think graphs, informational videos, or interactive maps, too.

Because nothing makes lies and pointless comparisons nicer than beautiful colours and shapes. Funnily enough I get spam offering me to do infographics for my blog. There is quite a market there.

Recognising the danger signs

There are a few sources I don’t retweet or mention and get very bored when people do. These are:

  • Blogs where every link in the text links to the same blog. This is lame SEO and pure arrogance. “This assumption is totally true as you can see in our article of last month” – what tells me that one was right?
  • Blogs that don’t link to the source or mention where you can get it.
  • Blogs that re-blog other blogs. These are the ones that didn’t get to be the first to have the piece of news, but are too lazy to do their own research which is a shame as they could make a news piece out of their competition saying nonsense.
  • People using fill sentences like “scientists say” or “in the expert opinion” whilst failing to say who these are.
  • Posts spelling utter devastation or total success. It is never that black or white

YMMV of course, but I’d rather give out some information that is coming from the source than keep an artificial discussion going that was first and foremost invented to get clicks.

TTMMHTM: Bond Mythbusters, security translation, boulevard wordpress and a ten year old tech writer

Monday, January 18th, 2010

Things that made me happy this morning:

How to write an article or tutorial the fast way

Saturday, January 2nd, 2010

As you know if you come here often, I am a very prolific writer and churn out blog posts and articles very quickly. Some people asked me how I do that – especially as they want to take part in Project 52.

Well, here is how I approach writing a new post/article:

Step 1: Find a problem to solve

Your article should solve an issue – either one you encountered yourself and always wanted to find a solution to on the web (this is how I started this blog) or something people ask on mailing lists, forums or Twitter.

Step 2: Research or code (or both)

The first step is the research of the topic you want to cover. When you write, you don’t want to get side-tracked by looking up web sites. Do your surfing, copy and paste the quotes and URLs, take the screenshots and all that jazz. Put them in a folder on your hard drive.

If your article is a code tutorial, code the whole thing and save it in different steps (plain_html.html, styled.html, script.html, final.html,final_with_docs.html). Do this step well – you will copy and paste part of the code into your article and when you find mistakes then you need to maintain it in two spots again. Make sure this code can be used by others and does not need anything only you can provide (for more tips check the write excellent code examples chapter of the developer evangelism handbook).

Step 3: Build the article outline

The next thing I do is write the outline of the article as weighted headlines (HTML, eh?). This has a few benefits.

  • You know what you will cover and it allows you to limit yourself to what is really needed.
  • You will know what follows what you are writing and already know what you don’t need to mention. I myself tend to get excited and want to say everything in the first few lines. This is bad as it doesn’t get the readers on a journey but overloads them instead.
  • You can estimate the size of the overall article
  • You can write the different parts independent of another. If you get stuck with one sub-topic, jump to one you know inside-out and get this out of the way.

It would look something like this:

Turning a nested list into a tree navigation

See the demo, download the code

Considering the audience

How do tree navigations work?

Allowing for styling

Accessibility concerns

Start with the minimal markup

Add styling

The dynamic CSS class switch

Add the script

Event delegation vs. Event handling

Adding a configuration file

Other options to consider

See it in action

Contact and comment options

Step 4: Fill in keywords for each section

For each of the sections just put in a list of keywords or topics you want to cover. This will help you to write the full text.

Turning a nested list into a tree navigation

See the demo, download the code

working demo, code on github

Considering the audience

who needs tree navigations? where are they used?

How do tree navigations work?

How does a tree navigation work? What features are common? How to allow expanding a sub-branch and keep a link to a landing page?

Allowing for styling

keep look and feel away from the script, write a clean css with background images.

Accessibility concerns

Consider keyboard access. cursor keys, tabbing not from link to link but section to section and enter to expand.

Start with the minimal markup

clean HTML, simple CSS handles, not a class per item

Add styling

show the style, explain how to alter it – show a few options

The dynamic CSS class switch

the trick to add a class to a parent element. allows for styles for the dynamic and non-dynamic version. Also prevents the need for looping

Add the script

Performance tricks, safe checking for elements, structure of the script

Event delegation vs. Event handling

One event is enough. Explain why – the menu will change as it will be maintained elsewhere.

Adding a configuration file

Take all the strings, colours and parameters and add it to a configuration file – stops people from messing with your code.

Other options to consider

Dynamic loading of child branches.

See it in action

Show again where it is and if it was used in live sites

Contact and comment options

Tell me where and how to fix things

Step 5: Write the full text for each section.

As said before you can do that in succession or part by part. I find myself filling in different sections at different times. Mostly I get out the laptop on the train and fill in a quick section I know very well on a short ride. That means it is out of my way.

Step 6: Add fillers from section to section

I then add a sentence after each section that sums up what we achieved and what we will do next. This is not really needed but great for reading flow.

Step 7: Read the lot and delete what can be deleted

The last step is to read the whole text (probably printed out as you find more mistakes that way) and see how it flows. Alter as needed and remove all the things that seemed a great idea at the first time of writing but seem superfluous now. People are busy.

Step 8: Put it live and wait for the chanting groupies

Find a place to put the article, convert it to the right format, check all the links and images and you are ready to go.

More, please, more!

More tips on the style of the article itself are also listed in the Write great posts and articles chapter of the developer evangelism handbook.

Writing for Smashingmagazine – what do you think I should cover?

Monday, December 28th, 2009

I guess it is a nice case of the squeaky wheel getting the oil… After complaining on twitter about smashing magazine overdoing the “list posts” – you know “543 jQuery plugins you really need” and “3214 ways to create drop-shadows” I was now asked to become one of the writers for the magazine.

I’ve always had a soft spot for Smashingmagazine as it rose quite quickly in an already full market and showed that dedication works out in the end. I’ve learnt a lot of my trade from online magazines, and later from blogs. Things like A List Apart,, Digital Web and Sitepoint taught me CSS tricks, basics of SEO and other tricks. When Digital Web shut down, A List Apart changed direction and other, interesting new magazines like Particletree just didn’t quite get off the ground I thought it was over and to a degree it is. Personal blogs, Twitter and Facebook groups change the idea where we go for information and the old-school editorial approach appears stilted and seems to hold us back.

I disagree though. A good editorial process means we deliver better content. Books are great not because of the author being a genius but because of technical editors challenging the author to explain better, copy editors fixing spelling and grammar mistakes and the same subject being prodded over and over again until it is the bare mimimun and easy to understand.

Where it goes pear-shaped is when your editorial work is not appreciated and the reader numbers (and ad-views) do not add up to the cost you have for paying writers and editors. Back when the first mags came out this was not an issue – people were happy to do this for free. Nowadays, however it is much more business and a lot of online writers ask for cash for articles. Seeing the amount of work that goes into a good article this is totally fine, but what if you cannot find good articles every day?

This is when mags turn to list posts. These are quick to do and mean a new release for the mag – the RSS feed gets a new entry, people can tweet it and so on and so forth.

List posts are a real problem. They are immensely successful, as they are easy to digest, but they are also killing the overall quality of a magazine. As Scrivs on Drawar put in in not very minced words:

It used to be so much better than this. Every article that you came across wasn’t a tutorial or list. Hell, the majority of them weren’t tutorials or lists. There were articles that actually talked about design. There were articles that made you think how you could become a better designer and encouraged intellectual discussion on design. Those articles still exist here and there, but they are drowned out by the copycats.
The web design community is split into two sides: 1. loves to view every single list article there is 2. hates that list articles were ever invented. I fall into both camps because to me some list articles do serve a purpose, but when we start to see Design Trends of Spa Websites I think we might be going a bit too far.

I was very happy therefore when Smashingmagazine approached me (on Facebook of all things) to write for them as they want to change and release more meaty, in-depth articles that cause a discussion rather than a flurry of comments all saying “awesome” or similar YouTube-isms.

So my first two articles I’ve written stuck on airports on the way to my parents’ for christmas will be released in January and cover the following topics:

  • Basic performance testing using YSlow, PageSpeed and AOL Web Page Speed test
  • A seven step test to find the right JavaScript widget

What other things would you like to see on Smashingmag and reach the massive amount of readers it has?

The Developer Evangelist handbook is out!

Tuesday, July 28th, 2009

Alright, after writing on it for four evenings and on one flight in between watching Watchmen and “The Boat that rocked” I am proud to present you:

The handbook explains several things:

  • What developer evangelism is
  • What makes a good developer evangelist
  • How to write for the web
  • How to use social media and the web to promote content
  • How to deliver great presentations
  • How to deal with criticism of your company and what to do with the competition
  • How to write easy to understand and useful code examples

The handbook is Creative Commons and free to use. I am working on getting a printed version out, too.

Here are shortcuts to the chapters:

You can also go to the full table of contents.