How to write clear instructions, Part 1

Let's say you're in a new contract job, and you're getting a crash course in how to set up and work in their development environment. It's a huge, complicated system. It would be great if there was clear documentation on how to accomplish specific tasks? And what tools are used for what (especially if you're only using each one for a small portion of the project) . But nobody's taken the time to create the docs.

It's all second nature to the regular members of the team. Coming from the outside, it all looks a bit like voodoo. When they show you how to do things, they just rush through it and switch screens without mentioning what the new one is. They just can't help it. They don't think about it in their day to day work.

They don't have step-by-step instructions on how to do it. You'll have to write those for yourself.

While they show you, write it down step by step. If they keep going before you can write it down, ask them to go back to where you lost them. Write down the file paths, and avoid short-hand. You need it as detailed as possible.

Don't assume that you'll remember it all later. Try to reproduce the steps right away, following your own notes. Missed a step? Go back and show them your notes, and where you got stuck. Write down what you missed, and try again to reproduce the steps and accomplish the task.

Eventually, it'll be second nature to you. But don't abandon your notes. See if there is a wiki or other knowledge sharing system that you can post them to, so the next person can use them.