How to design/plan for web application development?

Question

I'm interested in learning how to design/plan for web application development, in a multiple developer team scenario.

Assuming the role of "Project Manager/Lead":

1. What "documents" are needed for successful web application development?
2. What UML diagrams are needed and to what degree?
3. In the design/plan phase does each - as per use case - class need to be diagrammed?
4. How detailed (depth and breadth) should the class diagrams be?

If you have any helpful book/website recommendations, please share.

---

Follow-up (Added 11/18/09): What do coders/developers use as a guide during coding i.e. creation of classes, and their respective methods & properties?

If there isn't a complete (yet mutable) list of classes with their methods and properties, doesn't that ambiguity cause heavy reliance on each coders' knowledge/experience, resulting in deviations in code quality/usability/maintainability?

Answer 1

1. In all cases you must have a comprehensive and up-to-date record of the exact requirements. This includes both functional and nonfunctional requirements. It can be a Word document, a spreadsheet, or a specialized requirements system. You just need something that allows you to keep track of all the requirements and how they changed over time. Here's a good source of info and discussion about Agile requirements docs.
2. In my experience, use case diagrams have proved to be important, with component and deployment diagrams also being useful. Class and sequence diagrams can also be helpful, but in most cases I think those should be used more as basic mutable guidelines than immutable development requirements. Classes and methods are typically subject to change (especially if you're using TDD), and if you really want a diagram it's best to update it after code is developed rather that shoehorning your code to fit the diagrams.
3. I don't think each and every class needs to be diagrammed. I think that model class diagrams can be useful to keep track of where data is located, and occasionally some controller and view class diagrams are useful too. But in most of my experiences, the requirements and test cases have been the main source of direction in how the classes are designed, and they're refactored as the system grows and changes.
4. In model classes, I don't think anything more than the attributes are usually necessary. If you're modeling controller classes, it's usually wise to include both the major attributes and methods.

Answer 2

Depends on the type and size of the web app. If you're doing a small e-commerce website with a shopping cart then you'll probably spend more effort on the design side of things and less on the "app" functionality. Conversely, if you're building a large internal website with many data input screens then most of your time will be spent on the business logic and data rules.

Personally, I'm not a believer in rigid spec formats or processes. I'll customize to suit the project and the client with a view to communicating clearly.

Assuming the requirements are already documented, two types of documents I always seek to produce as a minimum for workflow-based data-intensive web apps are:

1. High level workflow diagrams indicating screen flow, status changes, and major actions. I find this very useful as a first step in fleshing out the the major movements within the application. The workflows usually correlate to the different use cases.

2. Screen specs for each input screen detailing each field's format and behaviour. Typically including the field type, default value, list values, data validations, visibility rules, and actions which can be triggered, etc. Basically a big table making sure the developers know how to construct the screens.

I've also used Balsamiq Mockups in recent project to whip together web app screens and the screen mockups have formed a vital part of the project specs -- very quick to produce, and they convey a lot of information about how the screens should work that is quite hard to convey in a text document.

Lastly, Joel's series on functional specs is useful reading.

Answer 3

Keep it as simple as possible.

A document specifying the core feature requirements is the first step.

Personally speaking, as web apps are nearly always database-based, I start off modelling the database based on the functionality requirements. The entities in the ERM diagram map usually 1-1 with classes in UML diagram, and already shows the basic relations.

Assuming a MVC architecture and well-documented code, the Model classes will be self documenting as they evolve (e.g. oxygen phpdocumenter ).

I find something simple like a wiki works best for writing docs rather than formal documents that can take longer to write than the respective code, particularly in an agile environment.

Answer 4

1. Requirements are one set of documents, which can include graphics, Word documents, e-mail messages, and other ways to record things. A list of what is in the development environment(IDE, source control, bug tracking), coding style and guidelines is another set of documents that can be useful in having a successful application development team. There is a project plan that is a big Gantt chart and release notes that are some more documents we create.
2. I haven't seen many UML diagrams other than what the Gang of Four have on their site for explaining some design patterns.
3. We have a backlog of items to complete and estimates of how complicated each story is. This may be different than the approach you are using. With our Agile approach, there may not be as much design/plan as your situation.
4. We rarely have class diagrams though Visual Studio does have an Object Browser that is handy for seeing what is already built.

Where I work we tend to work in pairs for creating domain objects and their members, methods and properties. Classes are created as needed for stories or if we are cleaning up or refactoring a set of classes.

There isn't a complete list of classes but there are some design patterns in use like MVP and faith that since a pair is creating something, the code will fit within the current style and guidelines. As requirements evolve there will be changes to the classes quite regularly but this seems like a natural way to do things for me.

Background on the environment where I am just in case anyone wants to know:

Where I work we have 5 developers, a QA lead, a business analyst, a team lead, an architect and a project manager as the main people in the project at the moment. We use Scrum, pair programming and some TDD ideas in our work.

We are using Visual Studio 2008, Subversion, HP Quality Center, ASP.Net 3.5, Sitecore 6.0, and MS-SQL Server 2005.

Answer 5

All the Use Cases must be well detailed, continued cooperation from the customer will always be a plus, still it could sprout unforeseen cases.

If developing interaction among different servers that will poll/push messages at different times you will be needing Sequence Diagrams for sure.

Avoid overdesigning it, in Class Diagrams unneeded classes tend to mushroom, cut them down, use more methods, keep track of what environment each class will really end up running (some will run server side, some client side - javascript - some will be scheduled jobs and run on the real server, some wil be cgi (or module) encapsuled by he webserver and run on demand, some will interface with the database.

Define the boundaries, make them clear. Server side/client side/database work are different beasts and may take different times and people.