Writing PostMortems for CODE

PostMortem Objectives

The objectives for CODE Magazine's Postmortem articles are similar to those of other post-mortems. Your project is complete. You used interesting technologies and techniques. You analyze what went right and what could have gone better. Some things turned out to be particularly good decisions, others almost sunk the ship. You probably learned some lessons, and we would like to communicate those to our readers in addition to just showing off your cool project and giving people something to be excited about.

Article Format

Postmortem articles start with a brief description of what the goals of the project were and what the overall scenario and boundary conditions were. Explain the type of project. Did you have a particular technology you wanted to use? Who were the project stakeholders and what were there top priorities? Who was the intended user base? What made the project different from your other projects or from your competitor's projects?

If you can, also tell us about your development team. What else have they worked on? What were the team dynamics? What's the corporate culture? ...

Also tell us about the tools you used in the project. Development environment, third party tools, hardware, ... You may also want to mention the intended runtime environment.

After you set the initial stage, the main part of the article begins. The core of the article focusses on 5 things that went well and 5 things that went wrong (referred to by the more positive term "challenges").

• List five points about your project that went flawlessly or better than expected.
  Were there any phases of development that you thought would be much harder than you had planned? Did a new programmer come on the team and inject great ideas or brilliant programming ability into the effort? Did recent technology become widely adopted by consumers that solved a particularly thorny development problem? Have new development tools become available that let you work more efficiently? Did you save money in certain ways you hadn't expected? Cut days/weeks/months off the schedule in some way you hadn't expected to?
• List five points about your project that were problematic or failed completely.
  Did the lead programmer leave the company halfway throughout the project? Did adapting to new technologies create unanticipated problems for the developers? Did your development tools let you down in some way or not live up to expectations? Did hidden costs creep into the project, and if so, where did they come from? Did the schedule slip for some reason? Was the quality control cycle problematic for some reason? Did features get axed because of scheduling pressures? We don't want you to look bad, but we want you to share potential issues people can learn from. We also want you to explain how you overcame these difficulties. That is why we call these five points "challenges" and not "failures".

Important: ttry to come up with things that went right/wrong during project that are likely unique to your project. Stay away from common and well understood problems and solutions (e.g., "communication between the team members wasn't good" -- that's been true of most projects) and focus on what made your project different from others. Surprise the reader!

Also important: We know you are nice people who do wonderful work, but the Postmortem article is not the place to engage in PR, display gratuitous self-aggrandizement or try to kiss up to your boss/client. You will of course get recognition and visibility by writing a CODE Magazine Postmortem, and this effect is desired and intended. But to get the most people reading the Postmortem, provide beefy information, not marketing noise. Try to focus on the actual development process itself and what you learned professionally, bearing in mind that the audience for your article is other developers and not your manager or client.

Include Images and Screen Shots

A picture is worth a thousand words. Include screen shots and other images from your application. People want to see what your application looks like.

Screen shots should always be taken using standard color schemes (especially if you include screen shots showing source code, make sure you reset Visual Studio (or whatever IDE you are using) to the default colors. Send your screen shots as BMPs without compression. Never resize or compress images.

Photographs always need to be sent in high resolution (300dpi min). Photos of the development team or your offices are often interesting.

Project Facts

We like to include interesting facts and statistics about your project. How many developers worked on it? How many classes did you create? How many builds did you create? Here are some examples of interesting ideas (some may apply to your projects, and you may even be able to produce other interesting examples):

• Number of full-time developers assigned to the project. Also, the number of part-time developers or contractors.
• Number of full-time, part-time and contract designers.
• Ballpark budget of the project (if allowed).
• Overall duration of the project.
• Tools used on the project (Visual Studio, TFS, etc.)
• Third party tools and products used on the project.
• Runtime and deployment environment for the project.
• If applicable, a public URL or download URL for the finished product.
• Hardware used during the development of the project (type of computers, CPU, memory, etc.).
• Size of the project (number of classes, lines of code, number of files, etc.).
• Other notable technologies used in the project.

Length of Article

The length of the Postmortem article should be in the 3000–4000-word range. Broken down, that allows you to write about 3-4 paragraphs on each of the wrongs and rights of the project, plus an intro and conclusion. If you feel more space is warranted, we are flexible, but please coordinate with us.