Why Writing Should be Part of Your Team's Development Culture

Writing things down is the best way to prevent common knowledge around a team’s development processes from being misremembered or miscommunicated. Documenting systems and practices around a team’s software development workflow stops tribal knowledge* from being the primary way that information is shared and spread amongst a team.

** I’m defining tribal knowledge here as the shared development processes of a development team that are never written down or formalized in any way, but transmitted ad-hoc. 

Don’t Rely on Tribal Knowledge for Communicating Processes and Knowledge

In a team that relies on tribal knowledges for communication amongst developers, new team members have to gradually figure out who to talk to about things like how to set up their development environment, the dependencies of the project they’re working on, or any other similar things (that are hopefully remembered and relayed to the new team member accurately!) that could have been figured out quickly had this knowledge and process been written down.

Whenever a team relies on tribal knowledge, it means that you’re opening room for potentially contradictory or incomplete information to influence a team’s development process, which can lead to miscommunications and misunderstandings. The time spent correcting errors that arise from this ad-hoc knowledge transfer will ultimately be less than the time spent documenting institutional development knowledge up-front.

If processes like installing the dependencies that are needed for a project, any build scripts that may need to be manually run, or any other configurations have that have to be made to build and run a project are documented, then onboarding new developers will be less time consuming, and less susceptible to miscommunications.

Ideally, you should set-up whatever project your team is working on so that your team members don’t have to spend time doing any manual setup once they’ve cloned the project repository.

However, if you haven’t set that up yet (or there’s some reason why you can’t) then that process should be well documented. Otherwise, your development team will spend a lot of time trying to figure out how to get the project to build and run on someone’s local computer - which, especially in the age of remote engineering situations, is rather difficult to do effectively.

Documenting Complex New Features

If you’re building out a new feature that’s technically complex and has a lot of moving parts, you should document it as much as possible. This has a few different positive effects:

• You can clearly communicate to your teammates how the system or feature works
• Any future team members will be able to have a clear understanding of the system without having to try to piece together how it works on their own; from scratch
• Documenting something that you built will also serve as a reminder to your future-self how everything should work – software is incredibly complex, and it’s difficult to remember how everything works together for a long period of time

Software is extremely complex, and it’s difficult to keep all the objects that make up the mental model of a modern software system in one’s head for any lengthy period of time.

A Note on Speed and Time

Out of necessity, software development in startups moves extremely quickly - not everything that should be documented can or will be. However, documenting technically complex features that are being building from scratch, or things that require several steps to implement (such as cloning a repository with lots of finicky dependency setup for the first time) will ultimately save developers’ time. Development teams will, in the long run; move faster since they don’t have to try to remember things that have been written down, or try to retrace steps in processes that were never written down.