views:

50

answers:

1

I don't want my PHP coder to write Javascript anymore. I want to separate javascript coding and php coding. How should I write documentation about this interaction?

Let's imagine really simple ajax request. As for me documentation should contain sequence flow diagram.

  1. user is clicking "edit" button
  2. preloader is shown to user
  3. ajax request is sent to url /ajax_request/category/{category_id}/; we are expecting answer in json format
  4. timer has started; if answer is not recieved within 10 seconds - show alert "Connection timeout, please try to refresh page and try one more time."
  5. ajax request is recieved into var data
  6. hide preloader
  7. check if data.success is false then show alert "Something goes wrong."
  8. put data.html in container

As you see, it is really difficult to explain this flow in text format. I know there is UML for describing such things, but I have no experience. All UML samples are too simple and I can't understand how to build more complicated diagrams.

Please, anyone (UML expert), could you show me how UML diagram will look for my example.

I really appreciate any help. Thank you!

+1  A: 

There are more diagrams for your problem. The question is :"What do you want to represent?"

  • Flow from your step 1. to your step 8 You shuold draw a Behavior diagrams. You can use an Use Case (diagram for represent the actions of user), Activity diagram (represent the life of a algorithm or process) or a State Diagram (if you want to represent the evolution of a specific component in the flow, f.e. the http request). Otherside, you can use an Interaction diagram for represent the interdipendence between server and client.
  • Structure Generally you should use a Class diagram. In simple way:
    • a class for client;
    • a class for server;
    • a class for the request;
    • bla bla

This kind of diagram is useless for the usability/functional activity for the user.

  • UML4WEB You can use the Diagrams of Conallen, who made an extension of UML for the WEB project.
alepuzio
Right now I will try to make some diagrams and will put em here.It will take some time, so question is still opened./
Kirzilla
http://img2.pict.com/66/20/96/2820920/0/screenshot2b103.pnghere is sequence diagram; as I figured out it is not suitable for such situation because we can't add any logic into this diagramNow I will try Activity diagram
Kirzilla
http://img2.pict.com/22/bf/07/2821050/0/screenshot2b104.png here is activity diagram; it is much better. The only thing I can't figure out how to display in activity diagram is "checking for timeout".
Kirzilla