Christian Heilmann

You are currently browsing the archives for the documentation category.

Archive for the ‘documentation’ Category

Explaining Developer Evangelism

Tuesday, October 21st, 2008

Ever since I got the fancy title of “Developer Evangelist”, people look at me cross-eyed and wonder what that is. The reactions reach from “oh so you don’t code any more” to “that’s marketing isn’t it?”. Both are wrong.

I see the job of an evangelist to validate your company and its products in the outside world. This means that you need to keep an eye on what your company is doing, give feedback and stop bad documentation and too complex systems from going live. In order to achieve this you get to know systems before they go out, play with them and write or help write their documentation. You also go out into the world, speak at conferences and go into companies for “brown bags” and find out how people use your employer’s products. The feedback you get from that helps you validate or defeat internal assumptions about “what every developer needs” and “how people use things”.

I am in Bangalore, India at the moment and was asked to train evangelists for the local market. A bit of a weird concept as you find evangelists internally – you do not train them to become one.

In a two hour session I was asked to outline what it means to be an evangelist and what to do and not to do. Here’s the outcome on slideshare:

[slideshare id=674444&doc=developerevangelism-1224563721992430-9&w=425]

In praise of mistakes

Thursday, May 15th, 2008

I’ve been talking to a lot of developers lately in order to make people work better together and get things done faster. One thing that keeps fascinating me is the length people go to not to communicate mistakes and problems.

We are very much happy to celebrate successes and point out the obvious benefits of what we produce and do, but there is an innate tendency not to own up to mistakes or to welcome people telling you what is wrong.

I once heard the quote “a good friend tells you they like your shirt, a great friend tells you that you have dirt on your nose before you go on a date” (I think it was on Sherman’s Lagoon).

Mistakes are a great thing. They hurt, they make us think, they make us angry and they make us learn. The one wrong thing we do with them is to take these negative gut reactions and vent them in the wrong direction in most of the cases.

This is how we are wired, the first cave-man finding a burning branch after a lightning storm will have put his hand in the fire and quickly found out that it is a bad plan. He then most probably told others (the ones he liked) not to do that. He probably also pondered to use that fire against the ones he doesn’t like – sadly enough something we seem to excel at as humans.

Making mistakes makes us fell inadequate and uneasy – we failed as the crown of evolution and should be better than that. They also makes us feel protective – we don’t want to own up that we make mistakes as that would make us look weak or stupid in the eyes of others. This is a mistake in itself as we all are fallible and do stupid things all the time.

Case in point: I was chuffed when my first A List Apart article was posted – having been a fan of the site for ages. The article JavaScript image replacement sparked a very strong counter-post by Peter-Paul Koch, aptly named Why ALA’s ‘JavaScript Image Replacement’ Sucks.

I was shattered. PPK was someone I looked up to and his post accused me of stealing his idea and code (we solved that riddle on a mailing list proving with time stamps that I did indeed neither) and his critique was partly very right but in other parts just over-zealous.

I was hurt, I was confused and – well – pissed off. Instead of grumpingly packing in or shooting back I actually looked at my code and fixed the issues PPK talked about. I also started communicating more closely with him and this started a long, great discussion and sharing of information and contacts.

I grew a lot by my mistake, and there are no hard feelings between PPK and me – I will be one of the experts talking at the conference he organizes later this year.

In short – making a mistake, being called upon it and fixing it made me a much better developer. It humbled me and made me realize that working with others (even if it is only for a quick sanity check) makes me a lot more effective than I could ever be on my own.

This can be applied to products: instead of celebrating the successes, we should be celebrating issues that have been brought to our attention. A bug is a chance to analyze what lead to it to fix it.

This is the real opportunity – we have to learn not to do stupid things. Instead of huffing and puffing and – worst case – putting in a “stop gap solution” or a “quick fix” we should spend time to see where the bug came from, what lead to it, what impact it has and document the way to fixing it. There are millions of “best practice” tutorials and examples but not many “here’s how we fixed a nasty bug that caused this and that” articles.

The reason is guilt and fear of appearing weak and fallible. Well, I personally think that owing up to the fact that you do make mistakes actually makes you strong. The same way that appreciating good work of competitors makes you more believable than just banging on about what you do and act as if others don’t do great things, too.

I am quite sure that if we managed to turn the development culture around to see mistakes as a positive, we’ll make a massive step forward. A person pointing out an obvious flaw is not a whistle-blower and “not on message” but someone you have to thank for providing a chance to really improve our work and learn not to do things wrong the next time around.

Mistakes are OK - they do happen.

Generating tutorials from source comments with Tutorialbuilder

Tuesday, May 13th, 2008

I am spending far too much time keeping explanation tutorials of scripts in sync with changes in the code. This is why I wrote myself a PHP solution to do the work for me. I’ve found over the years that the best way to explain a script is to :

  • Show an example
  • Show the full source code
  • Show the source code bit by bit followed by explanations what each part does

If you go and check Tutorialbuilder you’ll see that I managed to automate most of this with a PHP script. It does the following for you:

  • It generates the tutorial parts from comments in the script source code.
  • It converts the source code to displayable code (encoding it, adding line numbers, allowing for lines to be highlighted)
  • It creates a downloadable version of the script with a correct file name
  • It creates an executable version of the script without comments to link to with a script element.
  • It can minify the script (remove all whitespace to cut down on file size)

In other words, it turns this source script into a tutorial like this using a template and some CSS (most taken from the YUI).

It is not a replacement for JSDoc but instead catered to be easier to use and explain the functionality of code rather than the syntax of the JS code itself.

Tutorialbuilder is licensed with BSD, so go nuts using it for yourself.