DEV Community

Cover image for Here, There be Documentation
Kevin Lamping
Kevin Lamping

Posted on

Here, There be Documentation

"Honestly, does the client even care if the code is formatted or not?"

Have you ever had someone tell you this? Or maybe you're guilty of repeating that line. I know I am.

"Sure, I know standards are important, but we really don't have time to worry about that right now. The client just wants this feature shipped."

That's hard to argue against. The end result is what matters, especially when working for someone else. One the other hand, the idea of standards is to allow the team to ship faster (even if it takes an up-front investment). The client definitely cares about that.

So why are we unable to connect the dots between standards and the client's satisfaction? I have a theory.

Teams know standards are important, but they don't know how to make them happen. Typically, best practices becoming someone's "thing". Unit Testing is Allison's "thing". Code semantics is Bobby's "thing". Accessibility is Rachel's "thing".

But those "things" never become part of the collective mindset. There's no team ownership, no binding vision; just a bunch of things people are individually interested in. Managers encourage individual ownership, but withhold authority to implement the needed team-wide change.

An Adventure Starts

Let's think about what happens when individual "coding standard champions" are declared. Even when the team likes the idea, only the Champion makes the long-term changes needed to implement the solution.

Rather than addressing the lack of real buy-in from the group and the need for standards enforcement across the team, the Champion is encouraged to take individual accountability by management. This would look good on their mid-year review after all.

So the Champion goes off, fighting a huge battle to convert the codebase from the wicked ways of the past. They defeat the evil Tab dragon and travel back home with their Spaces safely in hand. It takes longer than expected, but feels good to have completed the work.

But what do they see when they arrive back home, weary from their travels?

Hundreds of new dragons hatching in the forms of poorly documented code and untested features. Why is no one dealing with these dragons before they become too big?! Oh, because it was the Champions thing. They're in charge of that.

So the Champion, still afraid to ask for real help, starts slaying these new dragons left and right. But then someone needs an outside resource and leaves the town gate open. New dragons come flooding in. Soon the Champion is overwhelmed with work, and fears another gate will be let open at any point in time, continuing the downward spiral.

So they put down their sword and the dragons take over. Someone asks months later, "Oh hey, weren't you fighting these things?" to which the Champion responds, "Yeah, but the client doesn't really care about dragons in our village, right? They just want to know the festival is going to happen and it's already a tight enough deadline."

Time Runs Out

Work continues and the festival time is near. There are dragons everywhere. They're eating the food. They're burning down the tents. Everyone is frantically running around trying to repair the chaos, but no one can get a handle on it.

The client is understandably upset. They hear talk of dragons ruining their festival and want to know why. To calm the client, promises are made to eradicate the dragons causing this chaos. But the festival must be moved back a couple weeks. The client, afraid to lose their investment, accepts the proposal.

Meetings are set up defining how best to slay these creatures. Champions are declared to deal with specific colors of dragons. Joe will take the green ones. Marcy will take the red. We'll meet in two weeks to see how things are going.

So Joe and Marcy start slaying dragons left and right. They're starting to get a handle on it; even teaming up in parts of town where there are a lot of both kind. They feel refreshed to have an ally in this fight and feel like they're making real progress.

Unknown to them though, the client is upset about the delay and wants a special tent installed as repayment. But Marcy is the only one who knows how to install that type of tent and she's already busy with very important work.

Without another rational choice, management decides to bring an outside worker in who specializes in all sorts of tents. They've promised to get this one installed in under two days. And they do. A couple days later the tent is up and Marcy and Joe have finished their work. All seems well.

Hidden In Plain Sight

The night before the big celebration, Marcy is walking around the various tents double checking tie downs and ensuring no dragons are lurking in dark corners. She comes to the special tent and notices something interesting about it. The beams holding the structure up are a different type of wood.

That's strange. Normally these poles come from a specific lumber mill, known for its quality. These must be different.

As she inspects closer, she notices strange holes in the wood. Then she notices it. The entire structure is swaying uneasily in the gentle breeze.

She immediately understands what's happening. The builder used cheap, rotted lumber — Lumber that's filled with wood-boring insects. These bugs are gnawing at the material, tearing it to shreds. She runs for helps as several adult beetles fly by her ear towards a neighboring tent.

She gathers the team in an emergency meeting. They decide they must hide the issue from the client. It's too late now to rebuild the structure; they can only hope it will survive the next few days of partying. They'll pull an all-nighter working to treat the bug infestation while the client sleeps.

A Terrible Success

It works. It works so well the client wants another party. In fact, the client wants parties like this every month. What a success for the team, right?

But they know the real truth. Their fixes worked, but they were unable to stop the bugs from spreading. The adult beetles surely laid eggs in every piece of wood throughout the fairgrounds. If they don't spend every day working to treat new infestations, the bugs will once again take over.

The damage done has required special scaffolding be put in to keep the tents sturdy. It's functional, but is delicate and difficult to adjust as the client's needs shift. They've already had to tell them that the jousting arena can't be upgraded because of "structural dependencies".

Joe, Marcy, and the rest of the team, once brave adventurers setting out to explore the landscape, are now confined to the city walls in a never-ending battle with the insects. Insects they had worked so hard at the start to keep out. They used the right materials sourced from the right people made in the right way.

But the client didn't care about that. The client just wanted a tent. And now Marcy has stopped caring as well. Why worry about using quality wood when it will just end up rotted anyway? This endless bug-squashing has worn her down. She's no longer motivated to start her day. Why should she? It's nothing new... just playing wack-a-mole against the insects.

New workers are brought in as she struggles to keep up. They also don't care about quality. They just need the steady income. They're satisfied squashing bugs. Every new tent for them means more job security. So they put up as many tents as they can, using whatever materials they find lying around.

Soon, the town becomes so filled with rotted wood that it becomes impossible to keep up the fight against the insects. Word is that the client doesn't like all the beetles buzzing around from square to square. A rumor has spread that the client is looking to move to a different town and a different company. A company that promises standards and quality craftsmanship; A company like this used one to be.

A New Start

In one last valiant effort, the team convinces the client to tear everything down and rebuild the city. They'll use the right materials this time. In fact, they'll invest in using the latest technology. Technology that comes with built-in pesticide. The beams are built to prevent insects from nesting, so it shouldn't be an issue.

The client is convinced and work begins.

Marcy, finding fresh motivation that she hasn't felt in years, sets up several meetings to help ensure standards are in place to keep this from ever happening again. She's excited to apply what she has learned to this new project. So many new ideas to try.

Her first: we must have quality control and follow strict guidelines in how work is done. People are excited, but a little skeptical. Won't that take extra time? Isn't this project big enough?

And honestly, does the client even care if the code is formatted or not?

Originally posted on

Header photo credit:

Top comments (0)