What are good guidelines for writing a design document to ease transitioning?

Question

I am transferring ownership of a project to a team far away. What are tips to smooth the transition? I am wondering about code-level transfer, so anything related to design docs, code-level documentation, etc. How do you document your prototyped code after the fact?

Answer 1

Years ago the only answer to this question would have been to generate formal use cases for all the features that are not yet implemented to cover coding going forward. Then the monumental documentation already produced would provide an architectural overview of the current codebase.

Nowadays though, I'm inclined to suggest a more agile approach to working with your far away team. It is important that you find someone on your side to guide the team every step of the way. Just tossing a bunch of documents in their direction is a good way to ensure that what comes back does not meet customer requirements.

To get started though, go back and generate documents to show:

• A usage model describing the features of the application from a users perspective.
• A domain model describing all the business objects that interact or are manipulated in your usage model
• An integrated UI showing how the features from the usage model might work together

There are several ways to write up a usage model. For teams that are not collocated, user stories work well because they break the features into very small parts and can include a user design demonstrating a mock interface.

The domain model can be UML or a class diagram since you are communicating the requirements to programmers. It'll be easy to understand using familiar diagrams.

I usually mock up a UI as a wireframe in Visio, HTML or Photoshop. But even just drawing on a piece of paper and scanning it will do the trick.

Once you collect the initial documentation, go back to your customers to ensure that everything is in proper order. Even better, involve the end users of the software in the documentation process.

After the initial handoff, have regular (weekly or monthly) meetings (online is fine...) going over what was done and what is planned for the upcoming iterations. When you see something that needs to be altered, it is important to plan the alteration in an upcoming iteration. Write the change up as a user story and stick it in the next iteration or the one after. Many times I will see clients that demand the programmers fix something immediately due to miscommunicated or inadequate requirements. But all that does is delay features currently being created and frustrate coders.

Good luck, let us know how it goes.

Answer 2

See http://stackoverflow.com/questions/400382/how-does-a-good-developer-keep-from-creating-code-with-a-high-bus-hit-factor#400436