What should you include in a development approach document?

Question

I'm in the middle of co-producing a "development approach" document for off-shore resources as they ramp up onto our project.

The most recent (similar) document our company has used is over 80 pages, and that does not include coding standards/conventions documents.

My concern is that this document will not be consumable and will therefore fail.

What should be in a development approach document? Are there any decent guidelines on this topic?

EDIT: The development approach document should detail the practices and techniques that will be used by software developers while software is designed, built, and tested.

Answer 1

In one of the companies that i worked, we had this whole process oriented approach with lots of documents (most of which were asked to be filled in by Project Manager). However, in spite of the length and explanations, i realized that it hardly used to help people -the real developers.

So i decided to pull on of myself with a specific objective of "helping the developers". The most important thing i started is to collect most basic questions - the real FAQs.

What i learned is that following matters to most people when they want to adopt certain process, and many things that they may not have prior idea but would appreciate right away if they understand the logic.

Here are the key topics that such a documentation should help:

1. The process of development to deployment - How should the code be organized, compiled, published (in the form of DLLs,libararies, executables, installers, webpages and how will they be deployed and tested).

2. How should we do version control. (and why if there are newbies). Understand how the structure of the repository, the code of conduct - when a check-in acceptable and when not, when a version/tag is announced, how the patch,marges will be applied, and what are the cleanliness expectations when a patch or release is declared done

3. Executing the Methodolgoy - are we agile, do we do up-font design, which methodology we use? Now given this, it might be a fixed for a given company. Now, for most people, they want to know how we are going to implement it for the given project. This is very specific about the project that will allow people to visualize different milestones and what is potentially important. In a research oriented project - we would want indicate "always validate critical algorithms before building on top of it" in a shrink wrap i would focus on the correctness and importance of features.

4. Communication responsibilities - Defining how do you make formal communication - this is not do with whether specific people can talk to each other - but people must have a sense as to what is important enough (problems, design decisions, feature freeze) to be either announce or even debated before proceeding on implementation.

5. Finally, we must all have a common understanding of code-quality, coding standard and in general what we think is ok or below hygiene level.

I wish i would start off every project with such a documents - however, it's not quite easy. But important thing is to address all issues that relates to day-to-day behavior and choices of developers. This goes long way when multiple releases to market needs to be delivered.

Finally, i would also suggest that try to be informal as possible. Usually, the process oriented guys don't quite like informal documents which can potentially be misunderstood out side the context. However, it should be done such a way that it connects the developers.

Answer 2

What you are calling the "development approach document" is typically called the Software Project Management Plan. (I've also heard it called the Software Project Plan or the Software Development Plan.) With those terms, you should be able to Google for some samples that are out there. As Victor Hurdugaci and Donal Fellows mentioned, the Software Project Management Plan you write will be (1) tailored to your needs and (2) updated as a living document as the situation evolves. That being said, writing one from scratch can be tough if you've never written one before and you don't know what else should go into it.

There is some guidance through IEEE Standard 1058 (IEEE Standard for Software Project Management Plans, 1998). There's a copy of the standard posted here. I find this plan to be pretty heavyweight, but it is a decent place to get ideas - and you might need the extra weight if you want it all in writing for a team that is offshore. There's also a pretty good outline -- and some great narrative on how to plan software projects -- in a book I turn to quite often for traditional (non-agile) software projects: Quality Software Project Management by Futrell, Shafer, and Shafer.

Answer 3

An approach document is a 'Neither here nor there' document. This is a document generally asked by Project Managers (Vendor Managers) of Business organisations from Project Managers (Software Development Managers) of Software Application Development Organisations.

The purpose of this document varies based on the needs of the Business Org PM.

Can contain hw architecture, system functions, communication plans, configuration plans, resource loading plans, technology stack, application architecture and so on..

again, the above list is variable based on the needs .. :)

am yet to see formal literature on such a document. if there are any by the standard authors Pressman etc. do share..

or am i missing something.

Answer 4

The most recent (similar) document our company has used is over 80 pages, and that does not include coding standards/conventions documents.

Since you already have some document(s), that's your starting point. Ask yourself:

1. What is useful in this document?
2. What is missing?
3. Why would(n't) I use this document?

After you get the answers, cut what is unwanted and add the missing parts.

The actual content of the document depends on the resources available and I belive is hard to speculate using the information provided.

Just a hint: you'll want to adjust this document over time so don't write too much ;)

Answer 5

Development practices change over time as your requirements change and as the set of languages, libraries and frameworks you use change. This change is inevitable and will mean that anything you put on paper is going to be outdated (almost) immediately. The way to deal with this? Keep it all in a wiki, and encourage everyone on your team — both internal and external — to help keep it updated and relevant.

Once you've taken the step from a dead document to a living one, the debate of what to put in becomes less urgent: you just put in what you can think of now and come back to it at a later date. (The good thing is that you won't have to understand everything in order to write the document in the first place.) You might also want to seed it all with the outdated content from the old 80-page doc; that'll give you a lot of outline material if nothing else, saving you from having to think about writing huge scads of boring stuff.

Answer 6

Keep the document short. Use newspaper style structuring - start with high level detail and follow with specifics. Instead of including standard practices - just reference them and detail deviations from the standard.

Answer 7

1: If you already are doing projects within your company, get on board with that process. Maybe even sub-contract out the management of your project development to them. Don't re-invent the wheel.

2: If you don't already do development in house, insist that the contractor you are using have a good methodology they use for projects. Then use that methodology.

Trust but verify. You are trying to weed out the garbage in the long-run. So don't let them do anything, follow any process with only deliverable at the end. Insist that early deliverable be done and checked before they move on.

Beyond that I basically ditto on @Dipan