These days, everywhere I look, I see procedures and documentation explaining how to complete a task. It's everything from a recipe online for a delicious coq au vin to instructions on how to wash your hands in a restroom. Our businesses are no different. If there is a task that you have to perform, chances are, you'll need to explain it to someone else one day. Companies want their employees to document these processes. I can't tell you the number of times that my division wrote procedures for various tasks while I was a submariner. After that, when I worked in support, if I fixed a unique issue, it was expected that I document the fix afterward. Here are some tips for helpful documentation that I picked up along the way.
Taking notes
The first time you sit down to write the procedure, I recommend performing the actions and taking copious notes as you go. Include a lot of details. This makes your instruction comprehensive and allows the user to easily follow along. You really want to over-explain here; then, when you go to draft the actual procedure, you'll have all of the available information and can cut away the unnecessary bits. The goal is to be thorough, but concise.
Placing notes
Anytime you need to provide additional information about the output or consequence of an action, it is preferable that you provide the note prior to the action so that the user can make the correct decision about how to proceed. There is nothing worse than carrying out a step in a procedure and then seeing a note about how you really should have used this flag or that option to get the outcome you desired.
Write to the new person
No, don't assume that your colleagues aren't smart. I know that not everyone is born with the same intellectual gifts, but that's not the point here. The point is, you should always write a procedure or how-to for the most junior person that could be using it. It doesn't do anyone any good if you write the procedure so that only your most senior systems engineer can read it, but everyone else has to ask for help. This goes back to the original point; you want to make sure to note every action, even the most basic ones.
Dummy check
Much like a writer uses a copy editor, a person writing a procedure should have someone else carry out the procedure independently. This way, the independent user can note where things don't work as described or places where you need additional clarity. With the expert there to guide them, you can fix any gaps in your explanations.
Get approved
This point will only get you as far as your organization requires. In some teams, anyone can write a procedure and share it. In others, it may require approval signatures from your boss, your boss's boss, and so on. For all of my military or government contractor people, it's not an uncommon requirement that procedures be signed by your department head and, potentially, the commanding officer. While this step can sometimes feel like a hassle or just "more red tape," it is definitely a good idea. If something goes wrong and you didn't get approval, you may need to refresh your resume. Be smart; get your procedures approved.
Take-away
I hope that you will find some use for these tips in your own life. These can be applied to your professional documentation and also your personal writing or blogging. If you ever wanted to write an article for this site, for example, these tips are a pretty good outline for how to get a "how-to" article started.
[ Free cheat sheet: IT job interview tips ]
