Story Time!
I needed to do a thing at work, but didn’t know how to do it. It was the second time the thing had needed to be done at the company. It would almost certainly need to be done again.
I could have spent an hour or two to figure it out, but I also had access to a subject matter expert.
Instead of asking for help, I asked the expert to document the process. We estimated that producing the documentation would take about 30 minutes.
30 minutes later, I ran through the steps in the document, adding minor corrections and clarifications that I found useful. I scripted the manual steps, added my script to the document, and, updated the Jira ticket with a link to the new doc and scripts.
Total time spent on this task:
- 30 minutes of my expert colleague’s time
- 15 minutes of my time
Versus an hour or two of my own time figuring it out from scratch, or interrupting my colleague over the course of an hour and burying the process in a private Slack thread.
Don’t ask an expert for help, ask an expert for documentation
- After 45 short minutes, we now had a validated document of steps that definitely work to complete a now-and-future recurring manual task, plus a script that mostly automates the task.
- The document captured a dependency installation gotcha that would have wasted plenty of time as I troubleshot it myself - but I didn’t have to.
- With the document and script, a new hire with no context can now do this thing.
- The document includes all prerequisite dependencies, some of which are not obvious and were left out of the expert’s initial Slack suggestions.
Be kind to your future self and team: ask an expert for documentation, validate the documentation, script what you can, and save yourself lots of time in the future.
Don’t offer help, you expert, offer documentation
If you’re the expert and someone asks for help, you should send them documentation instead. Write a document and ask your colleague to validate it. This will probably surface a lot of things that you, the expert, believe are obvious, but are actually not obvious at all and therefore need to be documented.
You, the expert, may be tempted to include a script in (or as!) your documentation. You can, but it may be more effective to let your document’s first reader produce the script, validating both their understanding and your explanation.