Product documentation problems your startup will eventually face

Every team that is building a product goes through several phases of team sizes and communication dynamics.

Stage 1: Rollerblading 👟

When it’s just you, building things is much easier, and faster. It’s easier to communicate feature details by just sitting and discussing across the table, maybe sketching out on a whiteboard and then jumping straight into coding. Things are slimmer , faster, more agile and you can pretty much decide to switch direction whenever you want. Communication is not a problem since its only you (and maybe another co-founder) but all it takes is maybe a meeting or a sketch to get on the same page. Any unanswered questions, loopholes in the feature can be sorted out in seconds. It’s in this phase that you build your MVP / version 1 of your product. Things aren’t exactly beautiful looking, (sometimes ugly even!), you have limited features, but then you are just testing out a concept so you move fast.

Team Size:1/2

What works: Small, agile, quick decision making, fast execution

Problems: No formal documentation, no reference

Stage 2: Skateboarding

Now that you have built a version 1 of your product, or (MVP) and you now have maybe a couple of (thousand?) users using it, you get a few more people to help you out. Now, you have a team of about 5–10 people. It’s not very big, so you are still pretty flexible, you can still brainstorm on a whiteboard, roll up your sleeves and build more.

But now, you need to start maintaining a note of conversations somewhere. A simple solution is to take a snapshot of your awesome whiteboard sketch and then share it on slack, or any other communication tool that you use. That at least brings a level of “documentation-sanity” by getting the team on the same page.

A simple one-page note or a document is always seen floating around somewhere where the team coordinates on. You are still fast and agile, but still need to get all 4 wheels aligned!

Team Size: 5–10

What works: More hands build quicker product and the team is still small so communication still fast and agile

Problems: Some sort of documentation is in place, but quality of documentation is still sub-par.

Stage 3: Motorbiking 🏍

This is the phase where things start to get really good. You have thousands of customers, and maybe by now they are paying you as well! So they have certain expectations from the product in terms of uptime, design, efficiency and support. So now you have a larger team. Simple means of communication like using just snapshots or sketches to discuss features is no longer a viable option.

You have a machine under you now — and it needs to run smoothly, avoid breakdowns, needs to be fuelled and tuned from time to time.

You can see your team communication starting to break down, a lot of to-and-fro happening between your engineering teams about details of the feature. If you have a support person, he/she will have several questions popping up, which again eats into precious engineering bandwidth.

This when your CEO/Product Owner/Product Manager need to step in and start writing formal feature documentation.

You start off by writing a feature spec doc somewhere. Google Docs, Dropbox Paper are excellent tools to start off with that are free, and can be shared easily with your team. Its still a simple document, but hey, as long as you have written a good enough feature doc and have noted all the nuances of the feature, your team can simply check the doc out whenever they have any questions. Of course, there still will be missing points in the doc, but that’s still better than what you started off with — No Documentation!

Team Size: 10–30

What works: Teams have some sort of a communication and collaboration system in place. Better structure, documentation and processes for sharing docs.

Problems: Each one still has his/her own documentation tool and possibly maintains docs in multiple places. Sharing still done via slack or email.

Step 4: Car Ride 🚗

At this stage, your product is doing well and you have a substantial user base. Your team size is also growing almost linearly and that means communication, document-sharing needs to become more formalised (but not difficult!) so that your team members are always synced up. By now, you will notice that every team (if not team member) is probably using their own documentation tool! Your product team is using google docs, but your engineering team is documenting their tech docs in GitHub! The design team of course would probably be using Adobe paper since its so elegant to use.

This might not necessarily be seen as a big problem right now, take a step back to look at the amount of steps needed to share docs, to access them and

Team Size: 30–50

What works: Teams will have split into smaller informal groups. Since the team size is still manageable, documentation is still easy to maintain and share.

Problems: Since there might not be a formal structure to the documentation, each individual team member might be using his/her own documentation tool of choice. Even though a formal folder or sharing structure would now be in place, it still becomes a problem to get everyone to follow it, making location documents and accessing it still a little un-optimised.

Step 5: Train Ride 🚂

Your team is now large, your product doing well and now you are also getting disciplined in processes. You can no longer discuss and finalise features as fast as you could before. Your team is big, its moving like a juggernaut in the right direction, but it’s not as agile as you were before. It’s not easy to communicate a new feature, or a release to a large team of people and make sure everyone is aligned with the vision and the endgame of the product.

As your team and your company grows, you will no longer be able to keep all team members on one product. By this time you would have broken down the team into different tribes or squads and each one would be using their own documentation format and tool. While this helps each tribe to be more agile and move faster, it becomes difficult to get a unified birds-eye view of what’s happening in the organisation in general. While project management tools still help identify what each team is working on quite beautifully, the location and interlinking of the actual documents — feature docs, tech docs, design docs are still abstracted away at a team level. If you, or any team member needs to locate a specific feature-related document, you basically need to ping the right person, get them to send you the link. If everything is done right, it’s updated in a Trello card or pinned in the right slack channel (in which case you still need to locate the right card or the right channel to find the document). While this still works, the amount of time you spend locating the document is time utilised on high value items.

Team Size: 50–100 and above

What works: Teams will now have split into smaller squads or tribes. Each squad might be working autonomously bringing parallelism in releases and better ownership.

Problems: Each squad will be maintaining their own documentation tool and format. While its easier for each squad to work independently and share and locate documents, it still becomes difficult to collaborate at an organisation level.

In this day and age of space rockets and electric cars, why is documentation and discovery of documents still an unsolved problem! While there are several really good products out there (like Atlassian’s Confluence) , so many of us still refrain from using these only because of the lack of simplicity. There will be some companies for whom Confluence really works, but there is a large segment of people like you and me who would really prefer something much simpler, does fewer things and gets the job done for us. And that’s where the next generation of products will line up.

Relate to these problems? Let us know more here
http://bit.ly/2pbjchW