How writing project documentation saves money and time

You may not want to write it, but you should. Here are three short stories explaining why.

Scenario No. 1

All similarities to actual persons, characters or events are purely coincidental: you got yourself one of those juicy senior software engineer jobs. New company, new people, new projects - everything is exciting, and you can’t wait to kick some ass and show everyone just how skilled you are. And then comes your first task. It’s an ongoing App development project, and your task is to make some changes. A walk in the park, right?

Riiiiiight. But if you could only find some docs about this project… Readme is empty. The task managing app has no notes on the topic.

How do you start this project locally?
Should you use npm or yarn?
Which version of node?
Any coding conventions you should be wary of?

Just why the hell no one ever wrote anything down? How hard can that be? You now have to find out who formally developed this thing and then ask this person a ton of questions, hoping you won’t make yourself look like an ignorant fool in the process. Imagine if this was a bigger task, a new feature God forbid - how many questions would you have had then? All this should be much smoother and less time-consuming. You just wish somebody had written those friggin’ docs.

Scenario No. 2

It’s Monday. You just came to the office, met your new colleague, brewed yourself a cup of coffee and started to work. Today’s task list is quite long, but you can make it.

And then the chat notifications start pinging: “Hi… sorry to bother you, but can you tell me how to start this project?” It’s the new JS guy. You explain for a few minutes and then continue your work.

Five minutes later, a new message. You respond again. Nine minutes after that, another message. This time you don’t know the answer by heart so you need to start the project yourself in order to remember and explain.

And whoops, just like that - you’ve spent an hour answering his questions. Now you have to postpone one of your tasks for tomorrow. A chain reaction of task transfers has begun. Your time is no longer under your control, it has a life of its own. You wish you had written those friggin’ docs.

Scenario No. 3

You work in a digital agency, and you’re starting a new project. During the customer discovery workshop and planning, you wrote down some notes and outlines of a plan, but nothing structured. You’ll work it out on the go, it’s important to start coding right away.

A few months in, all is well. Then the client asks when feature X will be done. Feature X? You don’t think feature X was part of the original scope. Both you and your project manager search through notes looking for planning history, but nothing is written on the subject. Here are your choices:

A) Accept the fact you’ll need to develop feature X, which might be out of scope, so you’ll end up not getting paid for that, plus your deadline will become tighter

B) Start a discussion with your client and potentially ruin the collaboration by insisting on additional funds and time

C) Travel back in time, write detailed project documentation, have it confirmed by the client before kicking off the project, and when this comes up you’ll have it all in black and white

Since time travel is not a thing yet, you’re stuck with A or B. It’s a cold day in hell. And, sure enough, you wish you'd written those friggin’ docs.

But writing docs requires time and money?

It does, but it’s worth the cost. Most of the time. Picture this: you're documenting a project that changes frequently, and changes a lot. The team is under pressure, they're coding their hearts out and fail to document a crucial alteration. Or stop writing docs for a longer period of time because deadlines and stuff. Before you know it, your old docs are super obsolete and not even you will find your way around them. And all that time invested into writing them just became a major cost infringer.

Yes, we still think having docs is mandatory. Just make sure you identify projects that will likely need frequent love and care and be serious about your decision to document before you start documenting.

Most often, not having docs is still the costliest option of them all.

Lesson learned, amigo?

A wise man once said it’s good to learn from your own mistakes, and even better to learn from the mistakes of others. Learn from these stories (they’re all real life experiences) and save yourself some time, money and nerves. And from all of us at Human, here are some extra thoughts on what makes good documentation good.

Mandatory

Have an introduction describing what the project is about and who will use it
Mention every person included in the project, both clients and executors
Define design and development timeline and deadlines
Write down all technologies being used
Briefly but comprehensively, describe every feature, every role and all of the use cases
If applicable, attach wireframes

For fellow developers

Define git contribution flow and deployment process
Specify how to start a project locally
Link the docs into projects Readme, and projects Readme into docs

Tips & tricks

Write this before coding and update if needed
Go the extra mile with document structure and formatting - split things into paragraphs by roles or functionalities, write headlines, let the reading be smooth
Ask someone to proofread it for you
Don’t get too technical - everyone needs to understand it, not only developers
Have it confirmed by the client after every change

There, you have it all now. All but an excuse for not writing friggin’ docs.

MARTINA ĐOĐO / November 11, 2022