# 2022-11-02 - BOOK-PROTO - Start prototypes with a diagram ## A good way to start a prototype The lowest fricition to starting a prototype is to get a pencil and a sheet of paper out and start drawing some ideas. You can write a few names of concepts that come up. I personally prefer to draw little boxes and fill in some concepts. It doesn't really matter too much if these concepts have a structure, if they are from different domains. For example, you could draw out the different users and functionality that they want to use, different parts of the interface, classes and api functions you can think of, infrastructure pieces, different programs and the way they communicate. The idea is to get them all out. The analog act of writingoften has a stimulating effect, and the more I write down the more ideas I get. Once you have a few of these concepts on the page, you can start connecting them with arrows, to establish the different relations that exist between them. This will quickly turn into a mess, which is why I like to use colors. Another alternative is to use a digitalmedium like an ipad, where you can not only move around parts of the diagram using copy paste, but also use different layers, tools like the eraser, filling surfaces,copy pasting different existing diagrams or screenshots and scribble on top. Another way to get started on prototype is designing wireframes of a finished product, and thinka bout the exposed functionality. While this might not even be the prototype you build, thinking about UIs is a good way to expose the underlynig functionality that you might wan to show to a uesr. Diagramming on a whiteboard is a nice activity. While I don't like doing it with a big group, it's a great wya to have a conversation with a colleague. Furthermore, it is erasable, and there are foten multiple colors of pens available which can be used to add different layers and dimensions to the concepts being talked about. Diagrams have a great property: they are universal across disciplines. In fact, I believe that they reflect something fundamental about human cognition. Humans think in terms of obejcts and their relations, and they understand that if an object is in relation to another object B, and B is inrelationship to C, then there is some kind of relationship between A and C. Sketching an idea out aas a diagram exposes theseobjects from the expertise field of one of the participants in a way that can be understood by another participant.That way, two people cancollaborate and exchange idea about the idea being prototyped. It is also a good way for oneself to start understanding a new concept, by laying out unknown parts and starting to understand how different parts relate to each other. That way, you can uncover hidden problems and assumptions as more nodes are added. It also offers a way to explore systematically. Once you have objectslaid out, you can for each object ask yourself "does this object have a relation to this other object?". This is especially useful when diagrams represent things like process flows, as missing arrows can uncover holes in the error handling, for example. Later on, these structures can be used to uncover where logging might need to be added (for example, if arrows are actions, then attaching logging is a good way to instrument your prototype). ## Concrete examples That first part was very abstract, and it is better to use a set of concrete examples. The first example I want to build is a very simple E-Commerce website. We can start laying out different components of the system, as classes: - user - product - order - payment - shipping - categories - landing page - category page - product page - inventory management - payment processor - webserver - webbrowser - email notifications This crosses a lot of different domains, and we might restrict ourselves to the database schema / the data we need to store. We can put these aside on a new diagram - USER - PROduct - order - payment - shipping we can now leverage existing types of diagrams, and tools that can generate those. For example, we can use a UML clas diagram notation (we don't need to be rigorous, any kind of annotation currently htat allows us to move forward is useful. Most probably the diagrams themselves will be discarded after they have been drawn, or maybe just photographed and referred tolater. It is not fully important to exactly document the thought process at this stage, the goal should be quick ideation and creativity.) We can now draw the arities of the relationships, and sketch out the fields of each of these items. We can now see that maybe we need to add new items: order line items - tax - shipping address - payment type and processor information - discounts Depending on where our fancy takes us next, we can start sketching out what the UI for the user lookslike, and draw little wireframs and connect the wireframes to our database objects. This allows us to create the database information that we need to render out the individual pages, and maybe how they relate in terms of navigation. This is a second stack of prototype diagrams that document another aspect of what we are going to build. ## Tools There are plenty of tools that can be used to create diagrams, although I am very partial to paper / whiteboard in the first stage, as they allow for creativity and speed. They also activate the body, and make one walk around and gesticulate in the contexet of the whiteboarding. Other tools that are very useful for quick iteration, and provide a bit more formality are mermaid and plantuml, which are pretty useful for programmers as they allow us to create 'CLEAN" DIagrams at the speed of typ[ing. They also provide structure, which can be good or bad. ## Other diagram types that are useful in that first approach I like two diagrams types besides the standard relationship box and arrows diagram type: - sequence diagram - state machine / process diagram The sequence diagram is useful to sketch out a process in time, one specific way to traverse the problem. It also identifies the participants in the process,m and which messages they use to communicate. This is especially useful in distributed contexts (which most programs are, really,kif you consider the use being an actor and the program irtself being an actor). The state machine diagram or control flow diagram allows us to consider the time and logic that the application needs. It is great to pracctice making these types diagrams really foromally, because the formalism then carries over into the quick prototyping phase, and allows one to already "write" code. In state diagrams, the boxes are states, and the arrows are transaitions from one state to the next. This makes it possible toe examine all possible states on its own, every transition from each state to another. I like making a list of the possible events that can happen on the left, so that they can be applied against each state to uncover missing transitions. I then like to annotate transition with the effects that happen, and start relating the individual states to the functionality of the program we are trying to write. ## QUESTIONS TOconsider when drawing diagrams Who are the actors? What are the communication channels? What are the data relationship[s? How does the data relate to its visualization? Who owns each piece of data? Which processes have logic and how do they move from one piece of temporal state toanother? What is the sequennce of events? Is there complicated control flow? Are there feedback loops? What is the flow of data? Where is data stored? Don't forget to incorporate humans into your diagrams: - users - maintainers - custommer support - ddifferent business organiation - programmers ane team structures (who own which component) - the release process of a big system is also something that can be diagrammed, as in a bigger context, systems are going to be mapped to human and business processes - deployment and infrastructure (once you design out apis for example, you can start thinking about multi-zone deployments) ## Using these diagrmas' The diagrams can be used for different purposes: - here we focused on using them for ideation purposes and uncovering hidden assumptions - we used them to htink about our problem in different dimensions'- we used them to refine what we are going to build, and potential scenarios that we want to tackle In a next step, we can use what we drew and clean them up, as a documentation step and using them for communication our ideas to: - colleagues in an RFC - statekholders to make sure we understand the problem correctly - ourselves to pick our ideas back up - as guides for implementation - we can transform sequence diagrams into unit tests or validation tests - we can transform wireframes into UI prototypes I oftenlike to keep photos of the diagrams we drew, and before ending the session writing down a little paragraph that captures why we drew a diagram, what it represents, and wht we learned from it. Without that concept, things can get really messy quickly. Exercises: - draw a diagram for the ata schema of an ecommerce system - draw a sequence diagram of a user placing an order - draw a sequence diagram of the content team adding a new product to the frontend - draw a sequnce diagram of an order being rejected because the credit card payment ismarked as fraudulent - draw a control flow diagrram of a checkout, along with wireframes of th user interface. connect the control flow to different UI elements - draw a diagram of the data storage, and who accesses the adata through which interfaces: customers, content team, admins, sales, accounting, purchasing, developers