Documentation for developers: Why you need to do it
- select the contributor at the end of the page -
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.
Takeaway
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.
