Throughout our history most of the big efforts humans have endeavored to create have been plainly visible. How's the bridge going? Well, look for yourself. How's the crop harvest going? You can see right there. Now here we are and some of the most important things organizations work on are intangible concepts in our minds and bits on a computer. I have to think there's prior art but we've coalesced on something that has proven to be useful to see where we are on our bigger projects. It helps us drive initiatives and get a shared *mental model* of what we're building. I see stakeholders, engineers, leaders, testers all refer to the diagram to drive discussions and get alignment. Sometimes while talking in person we'll physically reference different areas of the diagram when it isn't even in front of us; it's in everyone's head. This isn't a replacement for gantt charts, epic burn-down reports or even a well placed sequence diagram but it complements those things to gain alignment for everyone involved. The diagram can communicate a lot of detail but another thing I like about it is that you can blur your eyes, take a quick look and you have a good gut feel for where the project is. ## What the colors mean It's a very basic _boxes and lines_ but with color that has particular meaning. - **Black** means we have no work to do for this initiative but for whatever reason it's interesting to have on the diagram. - **Red** means we have identified work needs to happen but we haven't started writing *code* yet. - **Yellow** means we have begun writing code. - **Green** means it's production ready. - Testers have validated it. - Systems that depend on us have integrated with it and they're satisfied. You can see between _Back End_ and _Vendor_ we have 2 lines. If you have multiple API calls or use-cases between 2 things sometimes it's good to represent those individually. This can get out of hand, do whatever's useful. At least for me the *direction* of arrows doesn't indicate the flow of data. For me it's _source_ knows about _destination_ from a network perspective. You can infer source _depends upon_ destination for the arrow. Sometimes a single box is doing something really important but it doesn't represent a call to an external system. In that case if you _really_ want this seen on the diagram you could create an edge looping back to the box. Most of the times don't do this it's too much detail and doesn't help in coordination hand offs. ![[initiative_status_diagram.png]] ## What this initiative status diagram tells us - The **Mobile** team is completely done - The **Web Front End** team hasn't begun at all - The **Back End** is done with the `getUser` call but hasn't started on `getEvent` - We didn't have any work required of the **Identity Service** and we're done with our integration to them - **Some Service** has begun their work but we haven't started calling them - The **Database** work is all done and we're coding to it now - **Another Service** is working on things now and we've started calling them - **Another Service** is working on the API for the **Back End**, are the interfaces defined, can we start coding to that? ## Why this is good - Stakeholders understand the current status of the initiative. - Engineers get a sense of accomplishment when boxes change color. - During our weekly initiative calls we celebrate when things change colors, sometimes we'll update the diagram in real-time or share the updated diagram in team chats. - Engineering leaders are accountable for their systems and know the status of their dependencies and systems that depend on them. - Everyone knows where we are and we have a shared understanding of status and dependencies. - Dependencies become clear. Areas of stagnation are obvious. - It drives discussions, with a shared model product and process people can ask questions to the right people to help get rid of obstacles and get momentum. ## Further refinement - If there are multiple API calls or use-cases for integrations it's nice to draw a line for each one individually. - We sometimes get cute with dashed green lines to indicate more detailed level of done-ness. - Dashed green could mean it's done and validated by their own testers but the client hasn't finished coding to it completely. - Be careful, this can get more confusing. - Most capable diagramming software has the concept of _layers_ in the diagram. Those are great for hiding complexity for some audiences.