How to Make Documentation Easy and Simple

Whenever an employee somewhere puts in their two weeks notice, they will inevitably hear the words “will you please document everything before you go?”

You've probably been asked this when you've left a job. I have too. It's a common request and we usually don't think much about it.

But just because the document-when-you-quit method is a common practice, does that mean it's the best practice?

​I don't think so.

I've seen many developers try their best to document everything their last two weeks, only for their colleagues to complain that their documentation was either irrelevant to their problems or impossible to read.

But that's not even my biggest gripe about the document-when-you-quit method – I also think it's unnecessary.

There’s a far simpler way to document things so that employees don’t have to write all that documentation their last week – and this approach makes the documentation both easy to find and easy to understand.

How to Properly Document Things

Documentation should happen at the time of implementation – not when an employee is leaving.

I call this the document-as-you-build approach.

This approach is easy to implement. If you follow a standardized development project (with requirements gathering and quality checking), you will naturally produce all the documentation you need.

But the key for this approach to work is a good project management tool. JIRA is a good example of a tool to use; Trello is not.

Project management tools like JIRA are a great place to record notes and documents as you gather requirements and perform quality checks.

When you do that, you will produce all the documentation a future developer will need to troubleshoot a project. The only other step you may add is writing post-release notes on the project management tool. (I don’t think this is necessary but other people have passionately disagreed with me)

How I Relied Solely on JIRA for Documentation

My first job in business intelligence required that I fix bugs that stakeholders found within our team’s reporting solutions.

I could seldom meet with the developers who built these reports because they had already left the company.

Instead, I relied almost exclusively on past project tasks in JIRA. With that resource, I could figure out how and why the solutions were built the way they were built. I could then determine how to fix things without contradicting the requirements.

This worked well because all the previous developers on the team used JIRA to discuss requirements and quality check the work. Any documentation I needed was found in the comment section of those two tasks, as well as attached documents.

If you set up your project queue in a similar way, you can have the same benefits (and you’ll be less dependent on one single star developer or analyst to explain how things work to you).

There’s Other Stakeholders You Can Consult With

Even when you find gaps in information from the document-as-you-build approach, there are usually other people within the company that can add context to a project.

The primary stakeholder who requested the project is a great resource. You can ask them for additional context when requirement documents fail you.

People who currently use the reporting solution or input data to the source tool are also a great resource, when documentation is lacking. I once gained access to an accounting database with no documentation whatsoever. I was able to work with two accountants from the billing department to determine what every field meant, even though the databases had incredibly confusing naming conventions.

Lastly, the developer who QA’d the solution may also be available for questions. They probably had to ask the same questions you asked when QA’ing the original developer’s work.

But What About Process Documentation?

Not everything you build comes through as a project with a finished output. It’s perfectly okay to document those things in a separate environment that’s not relating to one project, such as a repeatable tasks or processes.

But that should never be something someone documents their last week. If there’s a repeatable task, the process should be written at the time it’s implemented.

What About Documenting How to Use Certain Tools? Shouldn’t An Employee Document That Before Leaving?

When people ask a departing employee to document everything before they leave, they often want them to document how to certain tools.

No employee should have to do that. If you have certain technical skills and you’re leaving the company, the company needs to hire someone with similar technical skills or train someone to replace you.

You cannot write a technical manual in two weeks that’s sufficient enough for those without experience to come in and fill your role – it’s impossible.

Trust me. I’ve been writing at least 20 hours a week for five years. You cannot write a sufficiently helpful technical manual on Tableau, SQL, SSRS, R, Python, or any other BI tool / coding language in two weeks (on top of finishing your current projects) for a newbie to come in and replace you.

If someone wants you to do that, point them to Udemy or some other education resource.

What Should I Document Before I Go?

Document the odd things in your job that are outside the standards of your profession.

If there’s something you built or did that a professional of equal technical skills cannot figure out by reviewing your work or existing documentation in the project management tool, then you should write a helpful guide to understand it.

Usually if I’m leaving a job, I think back on what I’ve built that might be “odd.” By odd, I mean those hacky solutions that were made because of unusual circumstances.

I’m not a fan of hacks because they’re usually band-aid solutions that break often and scale poorly. But sometimes you’re forced to implement a hack that might be confusing to someone else.

When those hacks do exist, I’d document that before leaving a company so that future developers can quickly review it and understand why it was done that way.

But this should be the exception to the rule – not the rule itself. If you find yourself having to spend your entire last week documenting everything, something is seriously wrong with the way you or your team approaches their work.