Mentoring Arun : Vol 5

On Friday, Arun and I talked mostly about two things - documentation and processes.

Arun is working on documentation and he was wondering whether or not he should document the failure modes of an external tool that is used as part of a process. This gave way to a broader discussion on what should be documented and when. In this particular instance, I talked about how documenting the failures of an external tool internally feels unnecessary unless the external tool has no documentation to speak of. There can be a basic expectation from the developer that they can look up the tools' documentation if and when necessary.

In general, we talked about deciding whether or not to document something depending on how much time it can save a person/company. If it can save a person one or more hours per week, the savings can add up to thousands of dollars per years. If the documentation can only save a few hours an year, then it might not be worth spending time working on that piece of documentation.

Also, when you think about creating documentation, you also need to think about how often that piece of documentation needs to be maintained. Do you take one hour to write it and never need to update it? Do you need to spend an hour every week maintaining it? Do you need one hour a month maintaining it? It's extremely important to understand how easily a piece of documentation can go out of date when working on documentation.

We then moved on to talking about boring tasks. I recently spent some time looking back at all the things I did at Enthought over the past 7 years so this question immediately made me think about all of the time I spent working on the Python 2 to 3 transition internally. Most of the work involved in doing that transition is boring. There are a few tools that mostly automate the task but you still need to consider all of the things that have changed between Python 2 and Python 3 when updating your codebase. Over time, we were able to put together a process for any team that wanted to transition from Python 2 to 3. Identify all of the explicit changes that need to be made in any codebase, organize them into subtasks that depend on one another and independent tasks, prioritize tasks as high risk and low risk and estimate how long the conversion will take depending on the manpower on the project. I think this is a good example of how it's important to identify the process underlying a boring task. The task might be boring but identifying the underlying process might help you automate parts of the task. You can document the process for other people. You might even be able to transplant the process to a different task, boring or not.

What do you think?