As many of us settle into our careers, we fall into habits—some are conscious and we know we’re doing them, but we’re just not actively thinking about them. Other habits are more insidious—we’re unaware of them, but are practicing them nonetheless. In fact, in order to build the list in this blog, I reflected on situations I’ve encountered and how I resolved them—or tried to.

Photo by Jaredd Craig on Unsplash

Documentation Is Write Once, Read Many

We have a saying in IT that “naming is hard,” but writing is harder. (I say as I write this post.) The labor that goes into creating a project is massive. Equally as important, but much less considered, is the accompanying documentation. While groups and initiatives like Write the Docs have helped prevent documentation from being completely forgotten, it is common to not only write sparse docs, but also to neglect to update them with code updates. When this starts to happen, the information you are providing people to work with your project becomes less and less accurate. It might go without saying, but that not only reduces people’s ability to effectively use what you’ve written—it also decreases trust in the deliverables you are promising and the information you have documented.

Solve this 🔦: Just like teams need stand-ups and sprints, projects need documentation. Normalize iterative documentation updates every time there are project/code updates.

I Only Need to Write for One Group/Audience

This assumption sneaks up on us as engineers and IT professionals. When we start writing our application or service, we usually write the immediate documentation for who we think will be consuming it—typically other developers, perhaps our coworkers, or maybe open source contributors. And after that, we normally stop.

Even within the developer community, there are multiple audiences to consider. Ask yourself:

• Does this documentation account for differences in discipline? Consider including information that would be needed for infrastructure requirements, quality assurance testing, data and business intelligence specialists, and so on.
• Does this application or service have non-engineers using it, and is there documentation available that is in a language that they understand?
• What is the minimum expected skill level of the user or consumer of your application or service?

The list can go on, but essentially, there are going to be many groups in your audience and you will need to accommodate them.

Solve this 🔦: Use some of the questions above to expand information for your product use cases, as well as outline the expected skill types and experience levels for everyone who will be interacting with what you build.

Documentation Needs to Live in One Place

There are strong benefits to having documentation in a single place—it doesn’t need to be updated in multiple places every time a change is made, and people will know where they need to go to learn something. However, where documentation lives is not a one-size-fits-all.

Consider what information you’re trying to store, who the audience is, how long it needs to “live.” Some tools, like wikis, are good for centralized information that needs to persist; however, it will not work for all project types. For example if you’re looking to collaborate on a blog post before it goes live, a tool like Google Docs might be a better fit. If you’re working with sales to document customer meetings, a more sales-oriented tool might be better for capturing that information. To complicate the matter, most of these tools aren’t free, so it’s entirely plausible that not all employees of a company will have access to all tools.

Solve this 🔦: Establish what information needs to live where, based on whatever criteria makes sense for your situation. It might be based on content, intended audience, longevity, and/or something unique to your needs. Once you’ve established what information needs to “live,” along with where and why, you can habituate those workflows on your teams.

${FAANG} Does This; We Should, Too

Photo by Martina Misar-Tummeltshammer on Unsplash

FAANG is the acronym for Facebook, Amazon, Apple, Netflix, and Google. These companies are the sources of a lot of innovation in our industry, in part due to the fact that they have massive engineering departments, user counts, and a scale that most companies could only dream of (or have nightmares about). This size and scale allows them to experiment in a way that more typically sized companies cannot. That said, it also means that some of the best practices that come out of these experiments cannot directly apply to most companies as-is, so the “let’s try these metrics that Apple uses” or “Netflix does this practice, let’s mirror that” approach likely won’t work.

Solve this🔦: Make sure to understand not only your business needs but also your organization’s size and scale. Definitely do make use of the amazing research that comes out of these companies, but be well informed enough to be able to adapt their practices and procedures to a model that fits your organization’s needs.

Some Next Steps

There are a lot of ways that you can start to break out of the bad habits shared in this post. The short solutions I provide for each are by no means all encompassing, but are a way for you to start learning more and branching out into better practices. If you have encountered these or other habits and got rid of them in your own company, we’d like to hear about it in our community.

While these corporate superstitions focused on documentation, in the next post of this two-part series, I’ll cover notification habits and behaviors, and ways that you can disprove and improve when you take a closer look at your processes.