Welcome!

Welcome to our collaborative engineering blog. Think of it as a team blog with guests as well from time to time.

Guidelines

Write excellent code examples

Code examples are what makes your posts and articles very relevant to developers. They say more than dozens of pages and – even more importantly – they invite people to play with your stuff.

Solve a problem with your post

We don’t need “hello world” examples that don’t do anything useful. Instead we should aim to give out code that solves real problems. Writing “hello world” code teaches people to write code, but not how to solve issues with it. Good code examples should answer the “how does this technology help me solve a problem?” and not the “how do I use this?” question. The “how do I use this?” question can be answered by documentation.

Show a working example

One of the first things to show in a code example is a working implementation. There is nothing more powerful than a way to see what the thing does by clicking a link or entering some data and sending off a form. You telling the readers that it works is one thing – the readers being able to try it out and seeing it for themselves is much more rewarding.

Explain the necessary environment

One of the things you want to avoid is people getting excited about your code and then not being able to make it work in their own environment.

Write working copy and paste code

Copy and paste is probably the most used way of learning code. You can write documentation until your fingers bleed, but the biggest use case is that developers will check a code example, copy and paste it, fiddle around with it until they get stuck and then start reading the docs.

Have the example as a download

Using a hosted code solution like GitHub this job is done for you automatically.

Based on content from developer-evangelism.com by Chris Heilmann