Care to talk about your documentation?

2020 has been a crazy year, and here in Maniak, we have learned many things throughout it. I believe that one of the most valuable lessons we have received is about the importance of documentation. Also, it happens to be one of the most underrated by everyone. (Yes, I'm talking to you, developer.). So, this article will settle a thing or two about what we talk about when we talk about documentation and why it's so important for everyone here in Maniak... and the world.

When things happen fast, we often forget to register them, and in any software company things tend to happen really fast. A client request comes in. We write a nice proposal for them. After a meeting or two, we make an agreement and start working our asses off to meet the client's expectations. We deliver, we have a self-congratulatory moment after the final demo. We publish. And then we start all over it again. No rest for the wicked, some would say.

During all this, a lot of things happen; a lot of problems get solved; a lot of data is generated, and usually, there is no place to put it. No log to write down our thoughts, no report to share our learnings and contributions, no cool way to track our progress, or generate visibility to our teammates and bosses. But it's ok. We usually make it work and deliver great products.

The real problem is that we are a growing company. We are gaining more experience, and more knowledge. More people are coming to work with us and our clients give us more and more challenging projects. Life here in Maniak is getting more complex. And here is where documentation came in. We need it, we are using it, and we are getting better at it.

Please ask what documentation can do for you

A well-intended, well thought, and sexy documentation project like the one we have must achieve four important things:

  1. Identify your processes to quickly see the bottlenecks and inefficiencies to improve them or get rid of them.
  2. Recognize the tasks that can be automated, saving time and resources.
  3. Help new employees understand better their job roles and the projects they will be involved in.
  4. Create a record of the company knowledge, be it technical, managerial, or even cultural. When processes and learnings are documented, no knowledge will leave when an employee walks out the door.

If you don't believe us that this is important, check out some of the direct benefits of documenting your processes and information exchanges.

A document a day keeps the crisis away

Amazing, right? It’s true that companies thrive when knowledge is shared and published. Project documentation includes a wide variety of documents, from project plans, processes blueprints, and business cases to requirement sheets and project status reports. (image)

After a fruitful documentation process, like the one I’m gonna share with you, you should end up with a well-written plan. A beautiful document that scrutinizes and discusses the way your company makes business and allows you to generate ideas, ceremonies, and artifacts that enable and enhance the company's growth.

How to document your company?

By now, I think it should be clear why documentation should be a vital part of any company. So here is some advice based on our experience.

The first thing on the list is that you have to know your company and how it operates. It sounds easy, but it's not. It requires a lot of thinking and a lot of listening. It doesn't matter if you are the founder or the CEO. No single person has the entire picture of how a company operates. You need to talk to everyone and gather all points of view of how the thing actually works; even the clients. Be patient, observe, listen, and write it down!

Then, you have to be able to translate all that data into something concrete. We found that the Service Design Approach is ideal to get started on a documentation project. This framework "is an operational tool that consists of planning and organizing a business’s resources (people, props, and processes) in order to directly improve the employee’s experience, and indirectly, the customer’s experience." It uses design methods, such as blueprints, to orchestrate the products, communications, and interactions, as well as, the operation, values, and structure of an organization. And the best part is that the underlying principles of this approach are that every service can be documented, measured, controlled, and improved upon.

So yeah, we used the Service Design Approach and we used it hard until we came up with Maniak's service blueprint: a clear image of the processes we follow and the interactions that happen within. This bad boy was the real conversation starter in the company. It gave us the visibility to start talking between us about the issues.

So we talked about it, and we identified the pain points of our company, where we excelled at, and where we needed to do better. With this information and our CEO's blessing, we set up the goals that will put us on track. For us, they were these:

  1. Standardize processes through documentation and generate an archive of Maniak's projects and best practices.
  2. Save time for the design and tech teams by providing them information about the project or a specific problem
  3. Back up PM decisions by creating brief documents exposing arguments and examples.

We had some serious issues: information gaps and leaks, time-wasting processes, and lack of documentation to back up hard decisions respecting the company's management. So we started prioritizing.

We would deal with the management process first, then we would take on the way knowledge transits across the company, to then focus on pimping out our design and development practices through research and accountability. Finally, we would focus on creating a company handbook that would gather all the previous documents into one. Our very own bible. This was the plan, and still is, but as you can imagine it’s a very serious endeavor.  

First, it is closely related to the company's culture. Documentation may be required to shake things up a little, and it's not always easy to change the way people are accustomed to working. So be patient, try to communicate your actions loud and clear, and always be sure to have the support of your leaders. That is key, my friend.

Also, once you start working on things, you kind of unravel a string of things that need to be fixed. Documentation demands you to be flexible. Sometimes you catch a glimpse of the light at the end of the tunnel, only to be forced to return to the very beginning because something just came up.

Also, be smart. Your documents have to be actionable and scalable. Don't waste time on a document that doesn't have an immediate effect, and please, don't waste time making documents on InDesign if no one in your office uses it. I mean, it's awesome and it looks great, but you need to remember the big picture. These documents must have a life of their own, and they should be available to everyone in your company. Try using a cloud-based storage solution (like Google Drive) and automation scripts; or like us, develop a platform that can absorb your documentation needs. Also, you could hire us, we could do it for you. We are good at it.

Anyway, documentation is fucking hard, it’s a long process but it's worthwhile. I am very proud to work for a company that excels at what it does and recognizes that we can always improve. Because at the beginning, documentation is a leap of faith. A lot of things can go wrong and real results take time. But once the machine starts moving, once the people start accepting it and living it, oh dear, it's growth time.