How can I persuade my boss for better programming documentation?

Question

I have been at my job for a couple of years now. I was brought on at a novice stage of the programming team, where it began to be officially recognized by the company, then quickly and largely expanded in size.

We develop and maintain a plethora of internal applications for our company. While we are a much larger size than 3-4 years ago(Roughly 12), we have way more active applications than we do programmers. Due to the quick expansion in size, a lot of applications have been churned out with little to no documentation created for them. During my time here, I have been commonly swapped in and out of various ongoing projects that require us to learn specific business processes.

What this usually means, is if I-or any developer- are put on a project, it often involves a lot of time researching what the application is, what the project will entail, then thoroughly learning a specific business process of the department that intends to use it. If it's an ongoing project, we often have to heavily reference veterans of the project or reverse engineer as much as we need.

About 2 months ago, I was recently put on an ongoing project that has been in development for nearly a year and a half. It encompasses several largely developed applications and various business processes from various departments. For the past several weeks, I found myself having to dissect the application I need to work with(Which feels like it takes quite a bit of time to do) before I can code. When I've grown confident in programming in an application, my boss moves to assign me to work on a completely different application, repeating the whole re-learning process.

I've been growing increasingly stressed out about work since being put on this project. I feel every time I begin to understand how a large component works, I am given a task that puts me back to square one. My colleagues, who have been on this project longer than I have, are mostly working on tasks that relate to the same application. I feel bad that it takes me a longer time to finish my tasks than due to needing to learn new application processes.

Documentation for these applications has been seldom developed and spread out into various places. I feel I can become more competent in working on this project if these applications and processes were more available for reference. I honestly really enjoy the aspect of the job that involves researching and documenting these processes. I've personally made it a habit to develop documentation for any new feature I develop. It also became a great way for me to thoroughly understand how an application/process works. The lack of documentation has been repeatedly brought up as a problem from our team, but they've mostly just been made as task items and left untouched in our large backlog.

I've repeatedly expressed to my boss that the lack of documentation has made working on my tasks go slowly, but it hasn't changed anything. I have weekly one-on-ones with him and want to persuade allowing me to dedicate time to develop documentation and saving them to a dedicated resource location. How can I tactfully talk to him about considering this?

Answer 1

At the moment your solution appears to be having all your developers dedicating a lot of time to documentation. That it's not very attractive to management - how's the development going to get done if everyone is documenting all the time?

It would be better if you simply start documenting things you discover as you learn your way into a project, and as you add features and solve things.

And the best place for documentation is in the project itself, alongside the code as readmes and comments.

Answer 2

Your mileage may vary, but I personally learn best by writing things down. So unless adding documentation is actively discouraged, after the phase where you learned everything about the software, there should be reasonably good documentation there. At very little cost, because I can type reasonably fast and typing uses very little of your brain capacity that you need to learn what the code does.

Answer 3

This sounds like one of those situations where 'it's easier to ask for forgiveness than permission'.

It sounds like you are already doing it.

What I would do is for whatever your current project is, start documenting it, investigate what tools you are going to use to do it (Are you writing documentation manually, using a document-in-code document generator?) and build a working POC.

Share it with your colleagues get their feedback on how useful it is.

Then take it to your boss and say 'hey I built this thing, what do you think about rolling it out to the other projects'.

Answer 4

Ask your boss to hire a technical writer as a cost-saving measure.

It sounds like you’re spending a lot of your time deciphering code to figure out how it works, and that’s reducing your efficiency by a large percentage. Calculate the amount of time you spend doing this, multiply it by your salary, and then multiply it by the number of people it affects to get a rough dollar value that it costs the business every year.

Then propose hiring a technical writer whose full-time job it would be to write documentation for your team’s projects as a cost-saving measure - by reducing the amount of time it takes to get up to speed when joining a new project, they would save the company more money than its paying them in salary.