Soldato
Recent development methodologies such as Agile emphasise the importance of communication over documentation. The idea being that so long as enough people know, the idea is unlikely to be lost - and that over documenting something that is likely to change is often just a waste of time and resources. Notably, people tend to avoid reading large documents if possible.
In larger companies with smaller software development teams, you might find that the development team is working on many different products over the course of many years. Products may be revisited and updated over that course and reliance on pure communication could cause ideas, even rationalisations for implementation details or, worse still, design decisions to be lost over potentially relatively short periods of time unless the communications are repeated frequently. As we know, people are forgetful.
So ideally you should have both communication and documentation. This introduces redundancy in the flow of information within your organisation. This is a good thing in that it means that communication can be checked against documentation and vice versa, but it could be a bad thing in that time is wasted in expressing the same information in different forms, and potentially confusion could be created if these things are not consistent.
Some solutions to this include things like JavaDoc, where documentation is generated from comments in the source code. This has the advantage of completing documentation as far as the implementation goes, but potentially lacks the communication aspect and likely misses out key information about design decisions, test results and so on entirely.
One thing that has been very popular in the open source community (particularly for older projects) is mailing lists. This is quite nice in that in a way, communications become documents. The problem is, they don't tend to be very good documents - they can be incomplete and navigating them can be something of a chore.
So the burning question of this thread is: How do we make sure information isn't lost about a project while minimising the amount of time and effort put towards that goal?
For me, I'd quite like to see something of an enhanced mailing system where communications are analysed through some magic black box. This magic black box would also accept searches, and spit out nicely presented documents constructed from emails containing relevant information. I wouldn't be surprised if somebody had already thought of that and implemented it already - so I would be interested to see if anybody has seen something like it.
In larger companies with smaller software development teams, you might find that the development team is working on many different products over the course of many years. Products may be revisited and updated over that course and reliance on pure communication could cause ideas, even rationalisations for implementation details or, worse still, design decisions to be lost over potentially relatively short periods of time unless the communications are repeated frequently. As we know, people are forgetful.
So ideally you should have both communication and documentation. This introduces redundancy in the flow of information within your organisation. This is a good thing in that it means that communication can be checked against documentation and vice versa, but it could be a bad thing in that time is wasted in expressing the same information in different forms, and potentially confusion could be created if these things are not consistent.
Some solutions to this include things like JavaDoc, where documentation is generated from comments in the source code. This has the advantage of completing documentation as far as the implementation goes, but potentially lacks the communication aspect and likely misses out key information about design decisions, test results and so on entirely.
One thing that has been very popular in the open source community (particularly for older projects) is mailing lists. This is quite nice in that in a way, communications become documents. The problem is, they don't tend to be very good documents - they can be incomplete and navigating them can be something of a chore.
So the burning question of this thread is: How do we make sure information isn't lost about a project while minimising the amount of time and effort put towards that goal?
For me, I'd quite like to see something of an enhanced mailing system where communications are analysed through some magic black box. This magic black box would also accept searches, and spit out nicely presented documents constructed from emails containing relevant information. I wouldn't be surprised if somebody had already thought of that and implemented it already - so I would be interested to see if anybody has seen something like it.