Documentation for developers: Why you need to do it

- select the contributor at the end of the page -
Let's be honest: Documentation sucks. Most of the time it feels like a necessary evil that prevents us from doing good work. It's like we're being forced to spend time writing stuff down when we could be coding up that new feature, fixing bugs or putting out ops fires. Love it or hate it, documentation is an essential step for all developers.

Thankfully, there's a way to simplify the process, and it starts by reinventing your own definition of documentation; to start thinking of it as something you perform first rather than putting it off until the last minute. That's exactly what June Blender (queen of PowerShell help) proposed at this year's PowerShell Summit. She opened plenty of eyes with a simple, yet profound idea when she encouraged us to think of documentation as a tool to help in the design of the final product, rather than some tedious chore.

June's intention was to get people to write better help for PowerShell scripts, but the concept can apply to many other areas as well. It's just a matter of reversing your steps a bit. Instead of immediately writing code, bringing up a server or installing software, make it a priority to write it all down first (not last).

Sure, it may sound like typical project planning--and it's certainly similar, but on a much smaller scale. Typically, when embarking on a project, a plan is put in place. All the steps are laid out on the table with milestones, deadlines, tasks and responsibilities. Why not use this method of project planning for a single PowerShell script or even for a minor task that might take you a couple of hours to complete?

To get a better idea of why June's method makes more sense, let's check out an example of a PowerShell script I wrote. The goal here was to help aid troubleshooting on a server when an incident happens at known time, but no other details are available. I created this to parse through Windows event logs and text files, searching for events that happened between specific points in time. I wrote the entire script before writing any of the help, and it shows. Not only is the help way too short, but it doesn't answer many potential questions that the user may have.

Before starting on this script I should have written the answers to a few questions. Like this:

What is the purpose?  Why is this needed?

The first, and most obvious question: Why even take on this task in the first place? What's the purpose? To get cracking on the answer, you need to sell yourself on this task. You'd be surprised at how much additional detail and clarity come out of this one, simple exercise.

An example for my PowerShell script might be:

This script is designed to search a Windows system for all events happening within a specific timeframe. It was created to assist in the troubleshooting effort to track down root causes of problems where the source is unknown but the time is not. This script saves considerable time for the user because it eliminates the tedious task of manually searching Windows event logs for all events within a specific timeframe.

This script's ability to searching Windows event is helpful but it's capability of searching text files is invaluable. This could not be feasibly done manually by an administrator.

What do you expect to have as a result of the task being completed?

If this task were a runaway success, what does that look like? Be specific. Don't just say “the task will be completed." If a virtual machine is being brought up, an answer to this question might be:

By the end of this task I will have a fully-patches, Hyper-V virtual machine with 8GB of RAM, a 40GB VHDX attached via a virtual SCSI controller, a 2-core CPU and ready to have SQL server installed.

What is required to begin this task?

When writing code, this might be the parameters. When managing a server, it might be a live network drop, a functioning SAN or enough memory on the virtual host. These are the prerequisites that must exist prior to the task getting started. These are the things that, if not present, will always end up in the failure of your task.


Remember: Questions like these need answers first, not last. By fully explaining the inputs, outputs and by selling whatever task you're working on, you'll not only have useful documentation after it's over, but also a blueprint to work from.

Get our content first. In your inbox.

Loading form...

If this message remains, it may be due to cookies being disabled or to an ad blocker.


Adam Bertram

is an independent consultant, technical writer, trainer and presenter. Adam specializes in consulting and evangelizing all things IT automation mainly focused around Windows PowerShell. Adam is a Microsoft Windows PowerShell MVP, 2015 PowerShell hero and has numerous Microsoft IT pro certifications. He is a writer, trainer and presenter and authors IT pro course content for Pluralsight. He is also a regular contributor to numerous print and online publications and presents at various user groups and conferences. You can find Adam at his site listed below or on Twitter at @adbertram.