On projects I have worked on, there is usually some document, set of documents, intranet or internal wiki pages that specify the vision and technical requirements of the software system I am working on. On joining a project, I think it’s important to find and study this document. This may sound obvious in theory, but it’s not always obvious in practice. I advocate studying this document as it helps not just the getting up to speed on the project, but also on-going design.
The kind of document I am talking about comes with different names. It may be called a requirements document. Or it may be called a product whitepaper. Or it may be called an architectural design document. Whatever its called, there are 2 important things it contains – the product vision and the high-level functional requirements. The information I require from this is the goal of the solution as a product, not necessarily the architecture or implementation goals.
Usually, I am not provided this information when I join. I have to search for it or ask for it. I find this document valuable, because it goes into detail in explaining the vision of the system, the problem it’s trying to solve. It does this in much more detail than a verbal explanation – which is what usually happens on an agile team.What happens on most agile teams I join is that someone spends an hour or so to give an introduction to the system. While this is a great intro, due to time constraints it cannot go into as much detail and scope as the requirements document does.
There are some on agile teams who would wince at hearing the term ‘requirements document’, as it brings to their mind flashbacks of big-up-front-design characteristic of waterfall processes, that have produce verbose requirements documents that no one ends up reading. I understand that, and I am not advocating waterfall. However, what I find in practice is that most projects (agile or not) have the vision and functional requirements documented somewhere, by some name, and new joiners to the development team are not usually given this document except they ask or search for it.