Introduction
“Let’s be honest; someone knows how all this stuff works, right?” This is a phrase that may come up in many, many projects in several different SDLC atmospheres. Companies, over years and years of IT innovation, restructure, re-programming, retrofits, etc., contain a cobweb of functionality and features of many products that will often rely on the tribal knowledge of employees. Unfortunately, this requires a lot of time and effort spent on every project going through the exercise of documenting the current state of the ecosystem.
Documenting current state can be made a lot less painful through the use of the RML visual models. Through this series of posts, which I am affectionately labeling “An Exercise in Documenting Current State”, we will walk through how you can use RML to quickly and easily document the current state of your IT infrastructure in a visual format that can easily be consumed by anyone who needs to know how X, Y or Z works today.
For the example of this series, I will be using Reddit.com. Reddit is a link-aggregator and community-styled website that aims to be “the front page of the internet”. For this first post I will attempt to describe Reddit’s structure in two ways: first through text (as you may have to endure when researching current state), and then through the use of a Business Data Diagram, which is a conceptual model that can be adapted to explain any number of concepts. As these posts continue in the series, we will explore the functionality of Reddit through code review and feature analysis being taken from first-person use of the website, as well as looking through the open source code for Reddit, which is freely available online.
An explanation of Reddit’s structure, as a SME may relay this information
Reddit is a collection of various objects and containers that are all related to and through each other in various ways. Starting from a user perspective, we have three different types of users: User, Administrator, and Moderator. Administrators are the top-level managers for the website and have privileges associated with their role with respect to moderating the entire website as a whole. Moderators have privileges specific to the upkeep of “Subreddits” which will be explained later. A “User” in this respect, can be an Admin or a Moderator for any number of Subreddits. A user can submit posts to Subreddits, and submit comments to those posts. A user can “vote” on posts and comments by giving 1 “Upvote” (indicating they enjoyed the post or comment) or a “Downvote” (indicating they did not enjoy the post or comment). These are tallied for each post and comment that a user has submitted. Users have an aggregate “Link Karma” and “Comment Karma” which is the total of upvotes minus downvotes a user has received from all posts and comments they have submitted. Comment Karma can go into the negative, while Link Karma is restricted from being negative as no post can have negative Link Karma associated with it.
A Subreddit is a collection of posts submitted by users to that specific Subreddit. Subreddits have moderators, posts, and can be subscribed to by users. A user does not need to subscribe to a Subreddit in order to submit a post.
The visual explanation to Reddit’s structure, as explained by use of a Business Data Diagram
The BDD below is intended to match up to the description that the SME had given (above). Obviously, there may be some finer points of functionality that may require the use of call-outs, and may fall prey to needing updates based on new information. However, with a little knowledge of how a BDD works, it is easier to walkthrough a logical visual model then have to interpret a SME’s responses. Since the BDD is such a high-level conceptual model, it can be used to explain scenarios that don’t necessarily correspond as “Business Data Objects”. For instance, a business analyst may take issue with calling out “Comment Karma” and “Link Karma” since these technically could be construed as attributes of a user. It depends on what information you’re attempting to relay and how you want to relay it.
Furthermore, this model takes advantage of the fact that relationships may be drawn through objects so as not to have every object’s relationship to every other object needing to be called out. For example, a User submits a comment but this is not drawn on the diagram as it may be common knowledge. It is up to the interpretation of the analyst whether to call these things out directly or inferred through relationship.
Are you having issues rallying your subject matter experts to describe current state on all your projects? Consider using requirements models on-hand to provide a picture for your requirements projects on-demand and with less churn.
