6

We're developing a web application that is now growing to quite a few pages, all dealing with complex data and rather complex interactions between pages.

For instance, the login flow encompasses the following different possible requests to our controllers:

  • Login -> Forgot Password -> Send email [POST only] -> Password reset token -> New password submit -> Back to Login
  • Login -> Create New User -> Signup [POST only] -> Send activation email
  • Login -> Process new invite requests -> Main page

...and a couple of more different variations, all including sending emails, asking for verification/activation tokens; and that's not even starting to touch upon the multiple wizard-like pages for connecting to external applications and so on.

Is there a good way of documenting all of these different URLs, their parameters, and the ways that these interact with each other? For complex web applications, having a way to refer to all these different requests must be a rather good resource... And especially in terms of security, being able to visually inspect the flow of requests and spotting potential glitches. (Hey, why is this page a GET? It should be a POST with CSRF protection!)

I just don't feel like a Word document is enough... UML? xmldoc?

Not that it matters at all, but it's written in C#.

Improve this question
1
  • Moved the question from stackoverflow. Apparently this is a more suitable forum...
    – mgefvert
    Oct 30, 2016 at 2:32

3 Answers 3

Reset to default
1

Sometimes a picture is worth a thousand words. I'd create some sort of State Diagram or flow chart.

Image via Mirosamek at English Wikipedia

Improve this answer
1
  • 1
    Sequence Diagram is also an option. I recently found PlantUML, which takes a simplified markup language and generates UML diagrams -- including state and sequence diagrams.
    – Rob Crawford
    Mar 22, 2017 at 19:42
1

There's not a specific UML diagram for user interface navigation. However, you could "adopt" some of the existing ones.

State Diagram as RubberDuck as mentioned or Activity Diagram as IBM suggest.

State Diagrams looks good for drawing overviews. Activity Diagrams could be used to delve deeper into details of each state.

Improve this answer
1
  • Activity diagrams look interesting. I'll look into it more.
    – mgefvert
    Oct 31, 2016 at 13:16
0

There are numerous things you can do.

First of all, it is possible that you are actually supposed to receive large parge of this documentation, not produce it. Check with team manager or PM who is producing analysis and architectural documents.

If you were not successful with this attempt then there is the whole analysis discipline in front of you. I would merely address your pain points.

  • Most of the time URLs do not interact with each other. It is a user who executes some scenario clicking buttons and requesting URLs. A good way of documenting all of these is to start with use cases about user-website interaction and screenflows.
  • URLs and services are subject to change. Not to go crazy rewriting everything create layers of documentation.
    • Per user goal. How user interacts with application, implementation-agnostic.
    • Per user interaction with the system. How each user request is fulfilled by browser-facing web methods, what parameters and requests are used.
    • Per method. How each method does its job interacting with db and other backend methods.
  • You don't have to create UML diagrams for everything, but my guess is that you can find valuable to have a sequence diagram per user interaction/page/screen and activity diagram per method.
  • Create am exhaustive catalogue of methods/services including all the URLs, names and parameters. But not their usage and logic behind.
  • To "have a way to refer to all these different requests" introduce a reconciliation between the catalogue, the documentation and the sources. It largely depends on the tool you are using, start with wiki pages per method and links between them if don't have anything.
  • To deal with degree of complexity separate main scenarios (Login -> Main page) from alternatives (forgot password, registration, failed login attempt). Not to overwhelm the reader alternatives can be isolated from each other and main scenarios in groups per area.
Improve this answer
2
  • Good suggestions, thank you. Unfortunately the team is quite small - me. :) However, I have seen similar difficulties in larger systems as well. My main concern is that it's getting unwieldy, with code spread out over more than one controller, to add insult to injury. And even if it was refactored, it still would be quite large, and it's easy to miss a security problem somewhere when there's lots of code and lots of methods.
    – mgefvert
    Oct 31, 2016 at 13:13
  • Yes, difficulties are the same regardless of the team size. And strategy to address them is the same.
    – Vlad
    Oct 31, 2016 at 13:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.