Allocating Resources for Project Documentation
What would you suggest for the following scenario:
Ten developers have to create and design a complex system. This project should be documented for future developers and design decisions should be taken into account. These reports need to be done every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about what they helped develop and integrate, and then one person puts each of these documents together. The final document is likely to be incoherent or redundant at times, as the person tasked with putting everything together won't have enough time to tweak each piece.
Suppose pieces of documentation from each developer arrive just a few days before the deadline. The collaborative system (i.e. the Wiki) would not work as expected as there was nothing to read until a few days before the deadline.
Or do multiple people (2-3) need to write the documentation while the rest of the team is working on the actual development of the system? Developers need a way to communicate their design decisions and conclusions to technical writers. How can this be done effectively?
source to share
We approach this from two angles using a RUP-style approach. In the first case, you will have a domain expert who is responsible for developing the design of what you intend to deliver - if necessary, breaking off developers if necessary. In the second case, we use a technical writer - they document the application, so they need to have a good understanding of how it hangs together and you engage them right through the design and development process. In this case, they can help polish the design and make sure it matches what they think was being developed.
source to share
We use a merge (atlassian wiki-like-thing) and document all sorts of "things". Developers do this all the time, and we push each other towards the docs - we let peer influence decide what needs to be done. Whenever something new comes along, he is tasked with reading everything and figuring out what is still correct. Because of this, the wrong material is either removed or updated. We are happy when we can delete things;)
The nice thing about this process is that the relevant material remains and unnecessary things are removed. We have always "moved away" from more formalized requirements, stating that we can always create the documents they wanted, if they needed "them". "They" never needed them.
source to share
I think that alternative 2 is less flexible because it means a new stage of the project (although it can be in parallel with the tests).
If you are in an agile model, just add the documentation (following the guidelines) as history.
If you are on a step-by-step approach, I would nevertheless ask the developers to work on the documentation, following some guidelines, and review that design and code documentation. After all, you might have a technical writer reviewing everything for correct English, but this will be a kind of "release".
source to share
This is not complete documentation, but make sure the interfaces, etc. commented with Doxygen-style comments means writing code and documenting it closer.
Thus, developers must document what they are doing. I still think an architect needs a review to ensure consistent quality, but making sure people document what they do is the best way to ensure they follow the architecture.
source to share