This week I experienced first-hand the knowledge ramp-up that is required when joining a project of any real size and complexity. I had actually worked on this project for a short while already, but I hadn't invested much time in learning the structure of the code or the domain.
This got me thinking about the README file of a project. Any good README will have a step-by-step walkthrough for how to install the app, set up the dependencies, build it, run it, test it. A good README might have things like how to contribute to the project, and maybe contact information for the developers. These are all really important, and developers don't really think twice about adding them. But what about required knowledge for the app?
Obviously, if you're starting a project in a new domain that you have no experience with, you're going to be Googling relentlessly. What are the intricacies of the protocols used? How does the protocol work? How do I do something I need to do with one of the app's dependencies? You get the idea... These questions are pretty vague, but I'm sure you and everyone else on your project has asked them (and many more) in one way or another at some point. Yet, our go-to information source for this is still relentlessly Googling. You want to set up the project? README. You want to understand what the code is doing? Specs. You want to understand the ideas or principles behind the app and its underlying technologies? Just go search around on Google.
That's effort duplication. A major part of software is about removing duplication. Yet here we are, every member of the team relentlessly Googling for the same knowledge that the original developer has already spent time Googling for. Maybe the README is a good place to catalogue sites, protocol spec excerpts, Stack Overflow answers, pages in books, YouTube video markers, etc., so that future developers can know exactly what knowledge is relevant to the app up to this point. Obviously, experienced developers will know a lot, and perhaps not need to Google as much. But there will inevitably be newer developers, and their efforts should not be duplicated among other equally skilled developers. As they search and find solutions, they should document them.