How documentation leads to better teams (and products)

Alejandra Ramirez
4 min readNov 23, 2020

Documenting isn’t just for developers, it is crucial for team environments and digital products. Wikipedia defines documentation as “any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure”. In short terms, it means making a register of the things you (or your team) had done. Papers first, right? Documentation is important to let other people know that the things you created, exist, and how they came to exist.

That’s the base for documentation, it acts as the structure of your project, and it’s especially useful if your project’s too big. Let’s say, an app, or a whole website. And if you’re a freelance designer or developer you may be thinking “Wait! That’s too much work for a thing that could get done in a few days, I might spend one whole day documenting the thing!”. And to be honest, that’s fair, I think the power of documentation shows when you’re working with other people. Here’s why.

When you’re working alone, you take things for granted. That button? Yeah, that’s always 25x52 px and it’s used on this specific screen. We understand our mind pretty well, and if you’re freelancing and working alone, you probably have a consistent process or routine. But here’s the thing: Other people don’t know that.

And I know this sounds obvious, but it wasn’t necessarily obvious to me in the beginning. Other people don’t know what you know. When you confront that fact, there’s only one thing to do: Let people know what you know.

Easy peasy! Well, not exactly. Documentation is so hard that it’s unfair, letting your fellow designers know that the button isn’t always 15px may be easy. But then the questions arrive. “Ok, but in which cases? And what about the variants? Is it already a component? Why is it like that?”. You may be fully able to answer that smoothly, however, not everyone can do that. I couldn’t, and sometimes I still struggle to do it.

But struggling with documentation is why it’s so important, it tackles the problem of communication and soft skills, things that aren’t talked about that much in the industry. Being able to let your coworkers know the way you approach things is crucial to working in teams. Documentation has the same purpose, only with the difference that it’s written. When you document your process and the things you’re creating you’re essentially writing a small guide for your peers. A “This Is How We Design Here (for dummies)”.

Now, imagine having a big encyclopedia solely about your product, made by the team and for the team. The UI designer could easily look up how you previously solved a problem and implement the same solution. The developers could easily find the components they need and the snippets of code required for the project, even the product designer could estimate more accurately how much time is this flow going to take. It easily saves your team hours and hours of just looking for the stuff you need.

And yeah, it takes time, and it can be tough, especially for startups. Documentation isn’t something you can do in 1 sprint, 2 epics, or even 5 stories, it takes time, real-time. Months might fall short if your product is a whole, constantly growing app. But as I stated before, it’s totally worth it, when you invest 2 months in the documentation, it saves 5 months when designing functionalities.

I could end this manifesto here, but I wanted to share this 7-step process of making documentation for projects, it’s a little rusty but very useful if you’re new to this. So…

How can I document my projects?

  1. Start with the basics, estimated time, team members, and their respective roles and expertise. Not necessary to assign to-dos yet.
  2. Collect everything you need. From briefs to benchmark, components, and even inspirational things. Everything that your team uses daily must be there.
  3. Find inputs and outputs, doesn’t matter if it’s for a project, a component, a screen, or the whole product. You need to be sure what you want to achieve and how you’re actually gonna make it.
  4. List to-dos. Have a meeting with your team and talk about times, processes, deadlines, and to-dos. You can use tools such as Notion, Monday, or Clickup.
  5. Constantly verify the process. Add control points whenever you need them and make sure everything goes smoothly.
  6. Document!, you shouldn’t leave documenting to the end, however, if you are in a rush, it’s time to do that. Analyze your process, find errors, encourage designers, developers, and all of your team to list their errors and what solutions worked for them, encourage them to be organized when working with components and guidelines.
  7. Analyze and deliver. Collect all of the information you got from this project, organize it, archive it, adjust your design system if needed. Now’s the time to do this, even if it sounds tedious. And have fun!

Be sure to know that different things need different documentation processes. This one works for projects, but a design system documentation might take other steps. However, I’m confident in the power documentation has when working with other people because communication is key, now more than before.

See ya next week!

--

--