So, I work as a developer. We are a small team. The majority of the people (everyone except the project manager and the senior developer) are still in university. We have very flexible work hours, sometimes I don't see some of the people for 3-4 days.
You can imagine that communication is key here. We write a lot of emails and use a bug tracking system and as long as you are somewhat connected to the task you can be well informed. (as long as you read all the correspondence).
One of the weak points of the team is the documentation that people leave behind. The code is reasonably well written and as long as you take the time to read it in it's entirety you will understand it. (problem: this usually takes quite a bit of time when tackling modules of a couple of thousand lines of code) Note: There is very good documentation for the users which is written to the end users, however we are discussing the documentation shared between the programmers.
When a new person has to enter some of the things a part of the team is working on, or when someone has to modify old code or someone's old code things get a bit complicated. As I mentioned before sometimes we don't see eachother for days so unless the project manager knows(and remembers) the details of the code the newcommer will have the following options:
1 Read the source
2 Read the old emails with the discussions.
When you have to refactor large pieces of the code This is fine (esp the first thing) however when an algorithm needs to be changed or someone just has to use an old module as part of new module or script or whatever you can imagine that waiting to meet the guy who created the module or reading tons of emails will waste time.
I have started adding small documentation in the beginning of each module. It consists of:
- 2-3 sentences about what the module does
- A bit of information for each function that is not a part of another function. Basically what it does and some specific information about the arguments it takes if the arguments are objects. If they aren't I just write "see the source for more on the arguments"
Since I don't know if I am on the right track the question is simple: What should such a minimal documentation contain so it can give a general idea about what the module does and how people can use it?