Documenting Web Application Flow / Iteraction

Question

What artifacts / diagrams do use to document the flow of a web application taking into account links between static pages and how dynamic view components (html forms, JSP, Ajax, etc) interact with server-side components (Servlets, Struts actions, etc)? Do use UML diagrams?

Answer 1

Use cases as part of activity diagrams are used by some of mine colleagues, but this is good maybe for some static high level navigation overview.

I am about to develop custom DSL, which will resemble BDD scenario format used in Cucumber with Webrat, IMHO such scenarios contain enough information to create interactionand web page models.

Answer 2

I used UML state diagrams for documenting page navigation for web apps in the past.

Answer 3

We used UML class diagrams using a variation of Conallen's essay Modeling Web Application Design with UML. You'll find this essay has evolved into different incarnations around the net and has even become a book Building-Web-Applications-UML-2nd.

My 2-cent tour of the approach we used:

Following Conallen's paper, we defined a new UML entities (stereotypes) to represent a web page or portion of a page so that we could distinguished the server-side code (e.g. Java servlet or JSP] from the client-side HTML/javascript/AJAX that it generated. For example:

• [web page]
• [nav bar]
• [page-content]
• [header]
• [footer]

There were new associationss such as:

• [builds] - relates server-side code to the web page or page fragment it generated
• [apparent-link] - used between client pages on sitemap diagram
• [link] - URL link, i.e. GET request
• [submits] - form post back to server, i.e. POST request
• [client-redirect] - client-side redirect
• [server-redirect] - duh

Finally, some new diagrams (mostly just specializations of class diagrams) such as:

• [sitemap] -> like a class diagram - shows static relationships ([apparent-link]s) between [web page]s from user's point of view
• [page-generation] -> like a class diagram - shows the classes statically related to a displaying a specific web page: what code generated it, what code handles the post submission
• [page-composition] - like a class diagram - shows the things that make up a given [web-page]
• [sequence diagrams] - The only other change was that the sequence diagrams could now include client-side entities as actors.

The good news:

• we found Rational Rose icon extensions we needed to make the diagrams look half-decent.

The bad news:

• this approach was a lot work - we now had twice as many entities to model with since we were now modeling the client-side entities in addition to the server-side classes.

Read one of the Conallen papers for pictures of what I'm talking about, but as I said, didn't follow his approach strictly - we only took the pieces we needed. Hope this helps.

Answer 4

I recommend taking the 37signals approach to application development.

Each page needs to have purpose. Focus on that purpose first and design everything else around it.

Process:

• sketch out the main parts with a sharpie and paper
• List item
• ignore the details early on (they just get in the way)
• create something real as soon as possible (ie. create a few html files with links that go to other pages to show how the application will flow
• once the flow of the site is set then add the design components and start programming

It's much easier to add programming to something that has already been designed and thought out vs designing an app to work around existing programming (which in most cases requires code to be rewritten to adapt to design/flow issues which were missed at the beginning).