What are good and bad ways to document a software project?

Question

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.

Answer 1

First and most important, have the comments written in such a way that NDoc can parse them. This is the best way to have the code itself documented, as the developers have to change their development practices very little, and you can generate pages that explain the code without having to look at the code.

Second, getting developers to write documentation is not easy, and getting them to do it might be an exercise in futility. This is where products like Fogbugz come into play. They will help manage the development with tickets, help track check ins, and when your done an iteration, generate release notes.

In conclusion, your best bet is to find the most effective solution that fits in with the devs existing process. If it impacts their development process very little, they will be more likely to adopt the system.

Answer 2

G'day,

Definitely use a wiki. I'd recommend TWiki as it's an excellent and extensive implementation of a wiki without being too complicated to install and manage.

Here's a couple of initial thoughts.

Categories:

Start off with an initial ontology of what you want to capture but

• allow people to add new categories or sub-categories as required,
• allow people to retitle (sub-)categories as required and maybe as agreed for this one so you don't get fragmentation for multiple names for basically the same thing.
• let any initial (sub-)categories wither and die if they are left empty. Do this at the end of the project as some areas may only have entries towards the end of a project.

Tagging:

Start using a tag cloud. BTW here's an excellent plug-in available for TWiki to start classifying content early on in the project. Retrofitting tags is almost impossible to do. Starting tagging early also allows people to search for information that may be there already rather than having the same info located in multiple places.

HTH I'll come back and add more points as I think of them.

Answer 3

Worst for me than lack of documentation is excess of documentation.

Keep in mind that yes: it's really important to document your project, but also that the major part of your documentation is always at risk of never been read at all.

So, I think that a good starting point consist in thinking of your documentation more like something that you may use to introduce new developers to your project than an over detailed description of the inner workings of your software.

Answer 4

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 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, 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 meaningfull 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.