What are good and bad ways to document a software project?
documentation
Solution
I think the most important things to document are the decisions. This goes for everything from requirements to architectural choices. What are the requirements of module X? How are these requirements represented in the architecture? Why did you choose architectural pattern A over B? What are the benefits? The same goes for source code: it is common knowledge that commenting the why is way better than the how.
How you document these decisions does not matter that much in my opinion, whether you use a Wiki or a Requirements document made in Word. More important is that these documents are always up-to-date and that it is easy for anyone to access them. This can be achieved by using a wiki, or placing the documents under source control, as you say. If only a few have access to them, they are more likely not to get updated, and not to be read when necessary.
We use a Wiki for our current project and it works very well. It is easy to access for anyone (developers, managers, and customers) and a history can track changes, so you know what has been changed and why. Furthermore, we try to document the code in a meaningful way and document the major design decisions. We try not to document too much, e.g. minor things, as it is always hard to keep those things up-to-date and it is not worth the effort, imho.
Problem
I'm responsible of finding a good way to document the software project I'm working on. What things are important to document? Should documentation of code and design mainly be in the code in the form of comments? Should we put text files or Word documents directly in the source control togetether with code? Should we use a wiki? Factors to think about include how easy it is for the current team to create the documentation, and how easy it is for other developers to find, correct and extend the documentation later. My experience from many projects is that developers tend to not write documentation because the system for writing it is too complex or developer unfriendly, and that after a few years, new developers can hardly find the little documentation that was written. I'm interested in what approaches you have used in similar projects. What worked well, what did not work well, and why? Some key facts about the project: - The platform is C# and .NET. - We use Visual Studio and Team Foundation Server for source control and work item (task) management. - We use Scrum and test-driven development and are inspired by domain-driven design. - The software consists of a collection of web services and two GUI clients. - Other clients are going to integrate with the web services in the future. The integration will be done by other developers on other teams (so the web services form a kind of API). - SharePoint is heavily used throughout the development environment. Most projects have a SharePoint site, including ours. - On our project's SharePoint site we currently have a bunch of MS Office documents on things like requirements, design, presentations for stakeholders etc. Keeping everything up to date is hard. - We also have a SharePoint wiki for the development team only, where we document things in an unstructured manner as we go along. Examples include how our build scripts are organized, our testing policy, coding guidelines. - The software is an in-house application in a fairly big financial institution. - The software is developed by a team of six people over a period of ~1 year. - The developers are consultants hired in for this project only, and will not be available to help in the future (unless the client decides to pay for it). - The client has few guidlines for how this kind of project should be documented.