Technical Software Documentation

Interactive Architectural Diagrams
Project Overview
Process of visually documenting the infrastructure of a massive machine learning decisioning platform. Resulted in resource that has been used by many people on and off the team to onboard and learn about the infrastructure of the system.

"Lauren took the time to document all the various bits and pieces of this massive thing and she made the documentation accessible and beautiful." - Teammate


This is complicated

Understanding both the business use cases and the underlying technical infrastructure of a massive platform can be challenging. Throw in a bunch of corporate acronym's and it starts to sound like a different language.

As a developer on a machine learning decisioning platform I recognized that I did not have a great understanding of the product outside of the specific part I was working on. To be able to contribute more to the team I worked to create a visual documentation of the platform.

Audience Analysis

Oh, it's not only me?

At the beginning the audience for this work was myself. I created the documentation solely with the intention of using it as a reference to help in my every day work.

However as I worked with more people within the team I began to get the feed back that this would be a helpful tool even for those who already had a familiarity with the product. As a team we could also use it for on-boarding new team members quicker and presenting to stakeholders.

Information Architecture

Connecting the dots

I started off by writing all the different names, acronyms, technologies, and buzz words that I could think of pertaining to the platform on sticky notes. I used different color sticky notes to categorize the terms as to whether they were platform specific, external software, use case specific, etc...

I then took the stack of sticky notes to a giant white board and with the help of the different subject matter experts on the team started to define each term and place them on the board in such a way where I could draw the connections and relationships between each of them.

The first pass at trying to connect the dots. Some information has been redacted.

With the vastly different use cases the platform supports and the complex relationships between the underlying infrastructure my white board started become hard to process. The next challenge was going to be breaking the information up into more digestible pieces.

Information Architecture

Breaking up the monolith

I started with the highest level of abstraction. With the platform being a sort of black box with an input and an output.

Then started to dive into each of the use cases and how they use this black box platform to accomplish their goals. I broke up the platform into understandable amounts of information and figured out how to show the relationships between them.

Application Patterns

How to navigate all this information?

I decided due to time constraints to create the documentation in a Powerpoint. I wanted an interactive way to "dive deeper" into the abstracted black boxes that represented complex platform and its many parts.

I created an application pattern using dashed line boxes to show that this element had more information within. When someone clicked on one of these interactive boxes they would be seamlessly transitioned to the slide detailing that information.

This powerpoint began to grow as I added more and more details so I added a menu to easily navigate to specific sections.

I also recognized that a lot of acronyms and company specific names get thrown around in meetings so I wanted a way to search the document for specific terms. I added a glossary with links to easily find a terms within the documentation.

6 of the 62 interactive pages created as part of the larger document.


Presentation & Distribution

I presented the tool at the monthly share out. As it was distributed to the team I got back a lot of great feedback about its use in enriching the people's understanding of the platform.

"Very educational and informative.  This is a terrific resource for potential new tenants, tenants, and team members alike."
"Really in-depth, and shows just how intricate the entire platform is. Well done Lauren! It’s interactive and fun. Raised the bar here."
"Very nicely done and incredibly useful.  Now I can brush up on the parts of the platform I’m not very familiar with"