You cannot scale without documentation

If you’re building a business that grows like crazy, documentation should be a culture trait you should promote and look for in the people you hire. I realized this when we worked on a major revamp of Freshdesk’s product interface in 2017.

The team worked hard for close to a year on this project, and we thought we had a great launch in 2017, but soon discovered hundreds of features that we missed out. Our very own customer support team had to tell us about features that were part of the older interface, and we scrambled to build them later. A lot of times, we learned about product behaviour only after our customers told us about how much they missed them in the newer interface.

By the time we were working on the new interface, it was close to seven years since Freshworks was founded. Most of our early employees had moved to different teams (or even different companies). As a team, we truly underestimated the amount of nitty gritties that were baked into the product over seven long, but incredibly fast-paced years.

At the stage we were in, it was also impossible for people we had recently hired to know every little detail across the product. It would have been incredibly useful if we had had a single source of truth which was neatly organized based on parts of the product, so someone can not just read about usecases and edgecases in the product but also go back and understand why a *certain decision* was made.

If only we had comprehensive documentation, we should have been able to look up a feature by a tag, and see a history of decisions and changes that were made on that part of the product. In our case, though, there was no central repository for product features that was readable, navigable and comprehensive. Sometimes there was documentation, but it was poorly written, sometimes it was not shared with everyone, sometimes it was so poorly organised it might as well have not existed at all 🙂

I think if things aren’t documented well, especially in a business that’s growing like crazy, it doesn’t just affect the teams’ abilities to build things and ship fast but also slows down the learning for new hires, and prevents them from understanding the historic context of org, tech and product decisions.

The challenge is in building a documentation-first culture when everyone is already stretched to do too many things; making documentation a habit, sort of second nature for everyone. The challenge is in selling the value of writing and having things recorded down for non-immediate benefits.

If we manage to succeed in doing that, I’ll be sure to write a second post here 🙂

Published by shankarganesh

Product manager. I solve problems that matter, make mistakes along the way, and learn from those mistakes. And then a year later, I come here to share what I've learned :)

2 thoughts on “You cannot scale without documentation

  1. Hi Dinesh,

    We try and document things before something gets picked up for development (this includes problems as described by customers, the solutions we explored, the feedback from our customers on those solutions, and details of the final design we agreed upon – like interactions, etc.)

    But the truth is – we’re not at a stage where we capture every little detail before development begins. There are also a lot of things we discover during development, so we need to always keep updating our documentation to reflect the latest decisions, changes and updates even as the work progresses.

    It’s hard. But if you can build a habit to open up that appropriate document quickly and start jotting down any immediate decision you make and the resulting change in the feature you’re building, it’d be super helpful.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: