<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>Forem: Thiago Amerssonis</title>
    <description>The latest articles on Forem by Thiago Amerssonis (@tamerssonis).</description>
    <link>https://forem.com/tamerssonis</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F1256402%2F477a2da7-f278-4955-bad4-5441866a304d.png</url>
      <title>Forem: Thiago Amerssonis</title>
      <link>https://forem.com/tamerssonis</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://forem.com/feed/tamerssonis"/>
    <language>en</language>
    <item>
      <title>System Documentation 101</title>
      <dc:creator>Thiago Amerssonis</dc:creator>
      <pubDate>Mon, 12 Feb 2024 11:48:32 +0000</pubDate>
      <link>https://forem.com/tamerssonis/system-documentation-101-3c9l</link>
      <guid>https://forem.com/tamerssonis/system-documentation-101-3c9l</guid>
      <description>&lt;h2&gt;
  
  
  Introduction
&lt;/h2&gt;

&lt;p&gt;Have you ever been in a situation where you needed to get started on an ongoing project or even maintain an older system, and instead of getting right into the work you had to spend hours navigating through a pile of information just to understand where to even begin? Well, I know I have, and tell you what, it wasn’t fun… even worse, wasn’t just once!&lt;/p&gt;

&lt;p&gt;We understand the nature of this dynamic world of software development, where lines of code are constantly shaping the digital landscape, it feels like the fast-paced environment often prompts us to skip certain steps to swiftly reach the final goal and meet the almost impossible deadlines set by customer expectations, and often documentation is the first to go. However, the importance of having a robust system design documented cannot be overstated. &lt;/p&gt;

&lt;p&gt;Let’s explore the critical role of system design in the development life cycle and delve into the often-underestimated importance of documentation in ensuring the longevity, adaptability, and collaborative success of software projects. However, if you think this does not apply to you or your project because it has such a small scope, like building a microservice, and you’re assuming you don’t really need to come up with a design or a document, the truth is, even if it only stays in your mind and you don’t realize it, you are, in fact, designing the system, so you might as well document it!&lt;/p&gt;

&lt;h2&gt;
  
  
  What is System Documentation?
&lt;/h2&gt;

&lt;p&gt;In a nutshell, it is the collection of comprehensive documents describing the inner workings of a system, as well as, the design and even business decisions surrounding it. It can be thought of as the blueprint that will guide developers, support staff, stakeholders, and even end-users. Without documentation, you may find yourself and your team navigating uncharted waters and struggling to stay afloat whenever there is a need to perform maintenance, debug issues, or implement new features.&lt;/p&gt;

&lt;p&gt;These documents come in all shapes and forms and navigating all these formats we can choose from is overwhelming, on top of that picking the wrong one could get you wasting time on an ineffective document. Selecting the right type will come from experimenting with documentation yourself, and the more you do it the easier it becomes, like most things in life. Nevertheless, I understand not everyone has the time to navigate these waters through trial and error, therefore I hope to bring some clarity on this subject and help you make the right decision from the get-go.&lt;/p&gt;

&lt;p&gt;Yet, I will ask you not to be discouraged, even if mid-way through your document you realize it’s not going to work the way you expected! Don’t be afraid to start over, and you will learn that the next document you write, not only will be easier and faster but will also be much more efficient.&lt;/p&gt;

&lt;p&gt;Now let’s talk about some of these types and, hopefully, you’ll have enough information to make the best decision for your project.&lt;/p&gt;

&lt;h3&gt;
  
  
  Text Documents
&lt;/h3&gt;

&lt;p&gt;This is the most common type of document, and probably the easiest one to produce. Most common when documenting specification requirements, system design, user manuals, and technical reports. It is typically created using word processors or plain text editors, it is also the preferred format when writing README files for code repositories.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Project managers, developers, testers, and sometimes even the end-user, depending on the scope.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Flexibility to adapt around the project scope and target audience; allows for thorough explanations; easy to produce and read.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; When the scope is too large it will become dense and extensive; hard to illustrate complex concepts, relationships, and flows; reliant on common language understanding.&lt;/p&gt;

&lt;h3&gt;
  
  
  Spreadsheet Documents
&lt;/h3&gt;

&lt;p&gt;Well, these are very straightforward, they are very useful when dealing with data related to the project and sometimes even to track statuses if your team is lacking better tools, they can contain a matrix of decisions, test result reports, checklists, and many other useful structures.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Project managers, developers, testers, and, sometimes, stakeholders.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Familiar format; suitable for calculations and organizing data; easy visualization.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Can become too complex for large-scale systems.&lt;/p&gt;

&lt;h3&gt;
  
  
  Diagrams and Visuals
&lt;/h3&gt;

&lt;p&gt;My favorite form of documentation, by far. Is not as easy to produce for beginners but can be the easiest to read. Encompasses charts, flowcharts, UML diagrams, ER diagrams, wireframes, and visual representations of system architecture. &lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Developers, project managers, and stakeholders.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Allows you to convey complex information intuitively; facilitates understanding and discussion; is not limited by language barriers.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Can quickly become outdated if not maintained as the project grows; requires in-depth knowledge and experience to produce.&lt;/p&gt;

&lt;h3&gt;
  
  
  Code Comments
&lt;/h3&gt;

&lt;p&gt;A very niche form of documentation, these are notes embedded directly in the source code that explain the functionality. They are very useful for projects on a smaller scope as they would make up for the lack of external documentation, which could increase the velocity of the project without causing maintainability issues.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Developers and those maintaining the code.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Provide a critical understanding of complex code logic and sections; eliminate the necessity of external documentation.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Extensive comments can clutter the codebase causing code readability issues; can easily become outdated if the code changes without maintaining the comments; unnecessary on a well-organized and clean codebase.&lt;/p&gt;

&lt;h3&gt;
  
  
  Presentations
&lt;/h3&gt;

&lt;p&gt;These are very useful as project starters, as they can be produced quickly and can convey the project points concisely and directly, they will also guide the discussions on the project requirements and the direction of the more in-depth documentation.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Stakeholders, project team members, end-users (depending on content).&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Provide excellent high-level discussion points; good for conveying summaries; good for engagement due to its visual medium focus.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Have limited details; cannot be used on their own as they require inputs from a presenter.&lt;/p&gt;

&lt;h3&gt;
  
  
  Video Tutorials
&lt;/h3&gt;

&lt;p&gt;Are not the usual kind of documentation, although they do have their benefits, they have a limited scope of uses, normally as onboarding or enablement sessions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; End-users and new developers.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Visual and engaging, good for demonstrating detailed steps; can save the time of senior resources during onboarding.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Take a lot of time to produce and update; not good for quick references.&lt;/p&gt;

&lt;h3&gt;
  
  
  Knowledge Bases (Wikis)
&lt;/h3&gt;

&lt;p&gt;These are platforms that can contain a collection of documents and can be edited collectively. They serve a similar purpose as text documentation, and can also include direct links to other documents. Very useful when sharing publicly accessible documentation.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Project teams and end-users (public only).&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Promote collaborative knowledge building and updating; can centralize a multitude of information; allow for fine-tuned control of access to information.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Require moderation to ensure information quality.&lt;/p&gt;

&lt;h3&gt;
  
  
  API Documentation
&lt;/h3&gt;

&lt;p&gt;This is essentially an instruction manual for an Application Programming Interface (API) service. Describes functions, parameters, and expected responses of APIs. Can contain examples, screenshots, tutorials, and anything that may be useful in explaining the API's functionality, it is essential for external integration and understanding API usage.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; Developers using the API.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Enables third-party developers to use the API; increases the speed of onboarding of new developers.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Requires precision, consistency, and ongoing maintenance.&lt;/p&gt;

&lt;h3&gt;
  
  
  Prototypes
&lt;/h3&gt;

&lt;p&gt;Early versions or mockups of software with a focus on usability or core functionality. Can be created as a part of the development process, or as a standalone project to test concepts and prove values.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;- Target Audience:&lt;/strong&gt; End-users, stakeholders, and developers for gathering feedback.&lt;br&gt;
&lt;strong&gt;- Pros:&lt;/strong&gt; Provide hands-on user feedback early; help catch UI/UX issues before the full implementation; help validate core functionalities.&lt;br&gt;
&lt;strong&gt;- Cons:&lt;/strong&gt; Require upfront investment of time and resources;&lt;/p&gt;

&lt;h2&gt;
  
  
  Why is documentation so important?
&lt;/h2&gt;

&lt;p&gt;During the system design phase, critical decisions regarding the architecture, structure, and functionality are made to ensure that, in addition to meeting the desired requirements, the system will also empower developers to anticipate challenges, plan for scalability, and create a framework that is both flexible and adaptable to future changes. Those specifications might give an indication of the complexity you will face throughout the project and while you may possess an impressive brain power to keep on top of everything you do, there is just so much data our minds can hold at a time. &lt;/p&gt;

&lt;p&gt;Recording all this information may seem like just an additional task on your already busy schedule, however, bypassing documentation and relying solely on memory to ensure the robustness and consistency of a system is not a sustainable long-term strategy. You will eventually realize that developing strong design and documentation skills offers numerous benefits that make it a valuable investment of effort and time. I will highlight some of the reasons I have found to be the most crucial and compelling, based on my own experience.&lt;/p&gt;

&lt;h3&gt;
  
  
  Communication
&lt;/h3&gt;

&lt;p&gt;Clear documentation is an essential tool in ensuring effective communication among team members and stakeholders. It helps convey the architectural decisions, design principles, and overall structure of the system. Considering the scale of the tech industry today, where you will most likely be working with people from all over the world, documentation is also an invaluable tool in bridging any language gaps.&lt;/p&gt;

&lt;h3&gt;
  
  
  Maintainability &amp;amp; Troubleshooting
&lt;/h3&gt;

&lt;p&gt;Legacy code is one of the biggest issues when implementing new features to an existing system, which makes documentation vital for maintenance. It allows developers to understand the existing design, making it easier to identify areas that need updates, enhancements, or bug fixes while ensuring the current features and code are not affected by the changes. Sometimes things do go wrong, and being able to react fast to issues is critical and it is only possible with a well-documented system.&lt;/p&gt;

&lt;h3&gt;
  
  
  Scalability
&lt;/h3&gt;

&lt;p&gt;A well-documented system design gives fundamental insights into how different components are interconnected, helping you identify possible stress points in the system and plan for future growth and on-demand requirements.&lt;/p&gt;

&lt;h3&gt;
  
  
  Onboarding &amp;amp; Knowledge Transfer
&lt;/h3&gt;

&lt;p&gt;Working as a team is not always straightforward. There are situations where time constraints require us to collaborate with others to speed up the development process, but this can be a double-edged sword as onboarding can be time-consuming, not only for the new resource joining but also for the project lead who needs to ensure the knowledge transfer. This can be mitigated by having system documentation ensuring effective knowledge transfer and faster onboarding of new developers or consistent continuation of a project whenever replacement of people is necessary.&lt;/p&gt;

&lt;h3&gt;
  
  
  Quality Assurance &amp;amp; Testing
&lt;/h3&gt;

&lt;p&gt;Ensuring the quality of a system is one of the most important steps in its life cycle. This will give the final product a strong competitive advantage, as a seamless user experience goes a long way for the reputation and trust of the software, while a bad one can cause irreparable damage to it. When planning the required tests to ensure quality, the documentation will allow the Quality Assurance (QA) team to navigate the details and complexities of the system, while executing and reporting on the tests.&lt;/p&gt;

&lt;p&gt;To further optimize the testing capabilities of the team, the developers can use the documentation to establish unit tests, these are automated and will ensure the reliability of a system before even getting to the QA team. This is the foundation for Test Driven Development (TDD).&lt;/p&gt;

&lt;h3&gt;
  
  
  Decision Making &amp;amp; Consistency
&lt;/h3&gt;

&lt;p&gt;System design will capture all the relevant details, specifications, and decisions regarding a particular software, and I can’t stress enough the importance of recording all this information. The resulting documentation will prove highly valuable when revisiting or reevaluating the system architecture, as it provides context for past choices, which will also be indispensable in guiding future improvements and supporting well-informed decision-making.&lt;/p&gt;

&lt;p&gt;It will also enable regularity in the development cycle, ensuring a uniform and steady adherence to the decisions and standards for the project, delivering a stable level of performance, no matter what point of the life cycle the project finds itself in, as it will always allow you to come back into the project and pick up exactly where you left off, without the risk of forgetting critical information and the need to reconstruct the system design mentally in order to get started again.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cost Reduction
&lt;/h3&gt;

&lt;p&gt;All the time cost that exists in software development can be greatly reduced via documentation. While this may seem counterintuitive, as documentation also takes time to  be produced, I assure you, the many more hours that you will spend looking for information, onboarding resources, refactoring the system, or fixing mistakes, will far outweigh the time spent on it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where to begin?
&lt;/h2&gt;

&lt;p&gt;Okay, so I've convinced you of the importance of having system documentation, or at least I hope I have… But how do we even get this started? Well, there are a few things we need to clarify first: Who is this documentation intended for? Are they technical? Is it for a customer or the internal team?&lt;/p&gt;

&lt;p&gt;These definitions will be your starting point for deciding the format of your documentation, although if you are in a leadership position where your job is to talk to customers, understand the requirements, plan the system, and then convey to both the client and the development team that is going to be working on this, chances are you’ll have multiple answers to the questions above and that  means you will most likely need more than one type of documentation.&lt;/p&gt;

&lt;p&gt;If you end up producing multiple documents you do need to make sure they are consistent throughout the project no matter who your target audience is or the form the documentation will take. The next section will cover how to do just that!&lt;/p&gt;

&lt;h3&gt;
  
  
  Stick to Best Practices
&lt;/h3&gt;

&lt;p&gt;I’d like to argue that, even though starting documentation from scratch can be daunting, it can also be an opportunity. By following best practices you’ll ensure good quality documentation from the beginning of your project, and by sticking to them you will make sure to maintain those high standards when updating your system and documentation.&lt;/p&gt;

&lt;p&gt;And what are these best practices? Well, first and foremost, whatever is agreed with the team you are working with. As they will be the main stakeholders of the documentation it is imperative that everyone is aligned and on board with the best practices to follow when documenting, some companies even have standards for documentation, especially the ones geared toward clients, and that should be your starting point.&lt;/p&gt;

&lt;p&gt;However, if you are truly starting from scratch and have no idea what these best practices can be, here are some pointers I can give based on what has worked quite successfully throughout my career.&lt;/p&gt;

&lt;h4&gt;
  
  
  Terminology
&lt;/h4&gt;

&lt;p&gt;Using clear and consistent terminology and notation will ensure the effective communication of your document. Stay clear of jargon, acronyms, and ambiguity, your objective is to be understood by the readers, and introducing terms they might not be familiar with will only cause confusion. I do understand that sometimes specific terms are required for certain projects but whenever that is the case make sure to define them in your documents’ glossary so your audience knows what it is about. This is particularly important when working with multilanguage teams.&lt;/p&gt;

&lt;h4&gt;
  
  
  Organization
&lt;/h4&gt;

&lt;p&gt;Keep your documentation very well organized. Make use of headings, sections, subsections,  table of contents, index, and glossary as these tools will help navigate the document and contribute to clarity and ease of access to your documentation. A well-organized document will help developers find the relevant pieces of information much quicker, boosting overall efficiency and speeding up the development process.&lt;/p&gt;

&lt;h4&gt;
  
  
  Format
&lt;/h4&gt;

&lt;p&gt;Finally, make sure you choose a suitable format for the documentation, one that fits the project requirement and the target audience. In my opinion, this is a critical part of the process and, sometimes, a difficult one. As I’ve shown you, there are several documentation types to choose from, each serving its purpose and they can even be combined for a more comprehensive document. So, take your time going through that list to make sure you are going in the best direction for your project.&lt;/p&gt;

&lt;h3&gt;
  
  
  Keep it Up To Date
&lt;/h3&gt;

&lt;p&gt;An outdated documentation can do more harm than good. While keeping the documentation up to date is arguably the most important best practice, I believe it deserves its own highlighted section. Imagine yourself trying to navigate a city with an outdated map, I bet you can picture yourself going into numerous dead ends, or even worse, getting on the wrong way of a road. Of course, there are signs that can point you in the right direction, but that might not always be the case either. You’ll find that software development is not much different. &lt;/p&gt;

&lt;p&gt;I’ve worked with outdated documentation before, while it is very distressing to try and navigate a system code or understand the expected functionality without documentation, having the wrong direction can set you back quite a bit, not to mention you could be actively introducing issues into the system and you might have to deal with messages from clients enquiring why something they asked to be changed now is back the way it was.&lt;/p&gt;

&lt;p&gt;This is all easily preventable by ensuring the documentation is up to date for every development cycle, be it during bug fixes or new feature requests. It will not only save you a lot of headaches and budget, but more importantly, time!&lt;/p&gt;

&lt;h2&gt;
  
  
  What's next?
&lt;/h2&gt;

&lt;p&gt;I know… there is a lot to take in. This is the start of your project and will help you shape it moving forward, so the best thing you can do is just get started. Don’t be afraid to experiment, it is better to have to start a documentation over than to refactor an entire system.&lt;/p&gt;

&lt;p&gt;If you are still unsure of how to proceed or what format of documentation will be the best for you, I would like to recommend a visual one, using charts and diagrams can be less overwhelming and a lot more fun! Not to mention they can bring more clarity to the more complex interactions of your system and they are very accessible to various levels of technical knowledge.&lt;/p&gt;

&lt;p&gt;A really good way, I’ve found, to practice documenting is to work on an existing system, preferably one that does not have documentation at all. Take a look through it and try to write down what you see, be it the architecture, code structures, services interaction, connected APIs, everything. If this is a project you were asked to maintain, even better! Now you have up-to-date documentation and once you start working on the task at hand, you can even complement the documents with whatever additional findings you may come across.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Thorough system documentation plays a crucial role in the success and longevity of any software project. While it may seem like an extra investment of time and effort upfront, the benefits far outweigh the cost. Having comprehensive documentation facilitates smooth communication,  streamlines onboarding, boosts maintainability, and ensures future scalability. No matter the scope of your system, having documentation will pave the way for your project growth, and despite the overwhelming amount of information we can add to a document, choosing the right format for your needs will get you there faster. And, of course, make sure to keep it up-to-date, as it will ensure the maintainability of your system.&lt;/p&gt;

&lt;p&gt;Now, if you are new to this and your documentation is lacking a bit at first, as long as you keep  working with it and updating it as you go, you will not only improve your skills but also set yourself up for success in the long run. And always remember,  your future self (and any other developer encountering your code) will thank you, so I encourage you to get started right away!&lt;/p&gt;

</description>
      <category>documentation</category>
      <category>systemdesign</category>
      <category>bestpractices</category>
      <category>development</category>
    </item>
    <item>
      <title>System as a Canvas: A Visual Approach to System Documentation</title>
      <dc:creator>Thiago Amerssonis</dc:creator>
      <pubDate>Tue, 06 Feb 2024 22:03:14 +0000</pubDate>
      <link>https://forem.com/tamerssonis/system-as-a-canvas-a-visual-approach-to-system-documentation-hai</link>
      <guid>https://forem.com/tamerssonis/system-as-a-canvas-a-visual-approach-to-system-documentation-hai</guid>
      <description>&lt;h2&gt;
  
  
  Introduction
&lt;/h2&gt;

&lt;p&gt;I cannot stress enough the importance of documentation for system design. It acts as a comprehensive roadmap, guiding the entire project by clarifying architecture, functionality, and relationships between components. Moreover, it ensures collaboration, reduces ambiguity, and facilitates maintenance. In the fast-paced environment of software development, where deadlines are getting tighter and the scope broader, finding time to craft efficient system documentation proves challenging. However, neglecting this aspect is a mistake in the long run.&lt;/p&gt;

&lt;h2&gt;
  
  
  Picking the Format
&lt;/h2&gt;

&lt;p&gt;There are multiple forms of documentation, each for its purpose, some of these are text and spreadsheet documents, diagrams, code comments, wikis (knowledge bases), and API documentation. In my years working with software and dealing with a few of these, I’ve found, through experience, that the industry tends to prefer text and diagram documentation, with code comments as the runner-up. Code comments are especially popular among developers, but they are typically internal and very situational, limiting their shareability.&lt;/p&gt;

&lt;p&gt;I've encountered my fair share of text documentation, which has a dissertation-like aspect and is common in conversations with non-technical stakeholders due to its readability. Although those can be used for the technical aspects of system design, they fall short of providing a holistic view of the entire project. As a consequence, spotting logical inconsistencies and potential issues becomes challenging in such dense documents. Additionally, this type of document has a major drawback, the language barrier. &lt;/p&gt;

&lt;p&gt;I am not a native English speaker, I am fluent in English today, but that has not always been the case. While on a regional scale, your team might not have issues with it, you must consider that in this industry, you can work with customers and teams all across the globe. Chances are, some of the people you talk to – more than you can imagine – will not be native or fluent speakers of the same language as you. Sometimes, even if they are, there can be some miscommunications due to accents and regional idioms. Therefore, this article will explore the form of documentation I’ve found to be the most efficient throughout my career: the visual one! &lt;/p&gt;

&lt;h2&gt;
  
  
  Draw it up!
&lt;/h2&gt;

&lt;p&gt;There is the most cliché saying of all times: “A picture is worth a thousand words”. This is a very well-known adage for a reason, and I can safely say it exists in many places around the world meaning the same thing and transcending language barriers. This is true in many professional areas, not only those related to images or storytelling, and in technology and system design, it is no different!&lt;/p&gt;

&lt;p&gt;Before we get started, let’s get some terminologies in place. When talking about visual system design, we normally work with diagrams. There are several types of diagrams as well, each for a different purpose and with a different style.&lt;/p&gt;

&lt;h3&gt;
  
  
  Types of Diagrams
&lt;/h3&gt;

&lt;p&gt;Diagrams are normally built following the directives from the Unified Modeling Language (UML), which is the industry standard for visual documentation. They can be divided into two main categories: Structural and Behavioral.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Structural diagrams:&lt;/strong&gt; are responsible for shaping the overall structure of a system, by utilizing static objects and indicating their relationships. Acts as a direct guide for the required technology in a project. The main structural diagrams include the Class, Object, Package, Component, Composite Structure and Deployment diagrams.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Behavioral diagrams:&lt;/strong&gt; focus on the more dynamic aspects of the system, establishing the interaction between the system components and how they behave over time. These diagrams help visualize the flow of data, communication, and execution within a system. The most common behavioral diagrams are the Use Case, Activity, Sequence, Communication, State Machine, and Interaction diagrams.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When working with system design, I typically incorporate aspects from both categories in the same diagram to give it a complete meaning. I found this approach to be more accessible and faster to spin up. Our goal here is to avoid investing a lot of time in building overly technical documentation that will end up requiring additional explanations or a lengthy document to accompany it. This, in turn, enhances our efficiency and production speed.&lt;/p&gt;

&lt;p&gt;Despite the flexibility to mix and match, if you are doing so, it is important to ensure that the final diagram makes sense and is understandable by anyone not directly involved in the project. This implies that individuals don’t need to have the full project context to understand its contents. I often find myself adding some aspects of sequence and interaction diagrams into a component diagram or incorporating architecture into either of these, depending on the system scope and how I believe it's most effective to convey the use cases within that scope.&lt;/p&gt;

&lt;p&gt;As the focus of this article is to guide how to produce efficient documentation, there won’t be much detail on the specifics of each diagram type. I will, nonetheless, give you a practical example of interaction and architecture diagrams (architecture diagrams are based on the component diagram) and show how they can interact with each other. Before we get into it, though, it's essential to decide where you'd like to create this documentation.&lt;/p&gt;

&lt;h3&gt;
  
  
  Diagraming tools
&lt;/h3&gt;

&lt;p&gt;There are plenty of tools out there that can facilitate drawing up a system design. It all comes down to your own preference, but truth be told, pen and paper can do just as good as a job, so there is no excuse not to draw it up. Of course, using digital tools has its advantages in keeping things clean and I would encourage their usage as they easily allow sharing and collaboration with others.&lt;/p&gt;

&lt;p&gt;The focus of this article is not to review specific diagramming tools in detail. However, whilst there are many excellent resources available, some of the tools I've used before and recommend are draw.io and lucidcharts. Both have a decent free tier, integrate nicely with most cloud storage solutions, and work very well for most diagram types. &lt;/p&gt;

&lt;p&gt;Sequence diagrams, on the other hand, stand as an outlier. For these, I like to use code-based tools such as sequencediagrams.org as they facilitate some of the more intricate details of this type of diagram and can very easily be converted to different tools.&lt;/p&gt;

&lt;p&gt;Once you've selected your tool, you're prepared to embark on planning your system design! It's worth noting that all the diagrams in this article were crafted using draw.io. Nevertheless, they can seamlessly be replicated in any other diagramming tool of your choice.&lt;/p&gt;

&lt;h3&gt;
  
  
  The Architecture
&lt;/h3&gt;

&lt;p&gt;Assuming you already have all system requirements, as well as user stories, it is time to start thinking about architecture. There are plenty of different ways to draw up the architecture diagrams. I don’t intend to explore in detail how to plan an architecture. However, I will give an overview to help illustrate the point. For that, I’d like to bring you a more practical example, and a small one at that, as you’ll see how valuable a full system design can be, even for the smallest of systems.&lt;/p&gt;

&lt;p&gt;Consider the following user story: “I’d like to send data of multiple formats to a 3rd party system”. From this story, we can infer that the input data will have at least two different formats, and this data will have to be transformed into a format expected by the 3rd party system. We can achieve this with a microservice that exposes a secure endpoint to receive data, transforms it, and maps it into the schema expected by the integrated system.&lt;/p&gt;

&lt;p&gt;This seems simple enough and you could probably do it all while keeping this system design in your mind alone. But, if you consider the following situation: you built this and six months later the 3rd party system was updated and now you need to go back and review the integration. Well, you’ll probably waste a lot of time just getting to understand what the initial requirements were and how the service was implemented. Or you can follow along and draw a design that will get you back on track even after so long, better yet, you could even delegate this task and not have to worry about it.&lt;/p&gt;

&lt;p&gt;Below, you can see what a diagram for this system could look like (note that I will be using AWS services as a frame of reference, but this can be translated to any cloud computing service):&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fbl1bxr2naxv9ox9f9rey.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fbl1bxr2naxv9ox9f9rey.png" alt="Image description" width="451" height="157"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Does this diagram bother you? If you said yes, good! While this architecture will accomplish the user story and is probably the first architecture that comes to your mind, it seems amiss. And that is only clear because we drew this.&lt;/p&gt;

&lt;p&gt;Looking at this, we can tell what the reliability issues are. If the 3rd Party Service is unavailable for any period, your incoming data will be lost in its entirety. Also, if you ever want to attach a custom domain to the service endpoint, you will have to review the entire process, not to mention the security risks of making the Lambda service endpoint public for it to receive messages directly.&lt;/p&gt;

&lt;p&gt;All of that will be clear once you start development and will most likely cause you to start spinning off additional services to overcome these challenges, which in turn may cause you to have to review the code multiple times and re-deploy everything several times more. However, since we have the drawing we can visualize all these complications without setting up a service or even starting to code.&lt;/p&gt;

&lt;p&gt;Now let's review this architecture and make it more robust and reliable taking best practices into account.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fgwzav9kyy466s5kucra2.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fgwzav9kyy466s5kucra2.png" alt="Image description" width="771" height="317"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;It is already looking a lot better, right? Now you can tell we have a system that won’t stop in case of failure, but more importantly, that can recover from failure. This can be expanded even further including more services to improve resiliency and maintainability. Of course, this diagram as it stands is very technical and is aimed at developers. If you are ever to share this with non-technical stakeholders you will need some additional notes on what each of these services do.&lt;/p&gt;

&lt;p&gt;Moving on to the next steps, while the architecture will give us a bird’s eye view of the system, the workflow diagram will give us a more fine-tuned perspective of what the integration service will look like, which is invaluable for developers to understand the system and plan for the code challenges.&lt;/p&gt;

&lt;h3&gt;
  
  
  Workflow Diagram
&lt;/h3&gt;

&lt;p&gt;This diagram is an amalgamation of the activity and component diagrams, providing a perspective on the interaction between components and overall system behavior. I have had a fair bit of success expanding on this by including architecture elements and adding some almost pseudo-code sections. That made the understanding so much better for developers and stakeholders alike.&lt;/p&gt;

&lt;p&gt;I had opportunities to test this form of diagram in real production situations, where I had to analyze complex system logic alongside non-technical stakeholders. Having a workflow diagram sped up the development process by leaps and bounds, with fewer iterations of logic adjustments compared to the times I did not have such a diagram.&lt;/p&gt;

&lt;p&gt;Continuing our example, see below what the workflow diagram would look like in this scenario.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fxwr5lokjqgurdd65uyvr.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fxwr5lokjqgurdd65uyvr.png" alt="Image description" width="800" height="1320"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The diagram above should cover all you need to build this microservice, it even has some aspects of a sequence diagram in the interaction with the 3rd Party Service, and should be fairly easy to read. Of course, in this context, the data mapping information should be elsewhere, but if you wanted to, you could add a JSON object as a note somewhere on the diagram to keep it all centralized in a single place.  Although this should be enough to illustrate for now.&lt;/p&gt;

&lt;p&gt;The more seasoned developers must have noticed by now that there is a stress point in this flow, and it becomes apparent thanks to the diagram. If you pay attention to the Authorization flow, which follows a standard authentication mechanism to request an access token and use this token for further requests into the system. In the flow above, we are requesting a new token every time we process an event. Though this would work out fine in testing scenarios, once this microservice starts receiving thousands of message events all at once, this volume of requests would cause significant stress to the 3rd Party Service Authorization endpoint. Prompting the security mechanism from the service to block additional requests. Furthermore, these tokens are normally valid for several hours, sometimes even days, and requesting a new token, every time data has to be sent as part of an integration, is not only a bad practice but can cause the service to shut down.&lt;/p&gt;

&lt;p&gt;Once again, we can see that because of the holistic view that a flow like this can provide of the system, even before we touch a piece of code. The alternative to this would be to start developing until we are done, and of course, our tests worked out without issues because we just sent 2 or 3 messages at a time while testing and adjusting, but once this gets deployed to production and more messages start coming in, the system would eventually stop. You would then have a distressed customer questioning why their services are being overburdened and, in some cases, incurring additional costs due to unexpected request volume on an endpoint that is not prepared for it.&lt;/p&gt;

&lt;p&gt;Now, going back to the diagram, we can easily fix that by introducing a cache that will keep the token throughout its expiration period and, therefore, only request a new one when strictly necessary. Here is how this flow could look like:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fcglpzkeblqi902cejld6.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media.dev.to/cdn-cgi/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fcglpzkeblqi902cejld6.png" alt="Image description" width="800" height="1639"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Much better right? When talking about coding this microservice, if you follow the diagram you should note that each rectangle can be directly translated into a function of the code and, as expected, the lozenges are directly translated into conditional flows (if or switch statements). This allows for a high-level view of the code and even gives an idea of what kind of libraries you might need. The best part about this diagram is that it’s very easy to read and provides developers with all the directions they’ll need for implementation. With this, you can finally start coding or assign this to your team and let them get to work! &lt;/p&gt;

&lt;p&gt;This flow has room to grow and it’s just an example of how we can achieve some simple documentation that will save a lot of time in the long run. Just make sure to keep track of any changes. This way, once you are finished, you will know where to resume if needed — whether due to a new customer requirement, platform upgrade, maintenance, debugging, or any other reasons for which you, or the current system owner, may be required to engage with this project.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Having clear documentation will always be beneficial no matter the size of the project. It will be your guideline throughout your project life cycle and allow for a more reliable and maintainable system. Although documenting small systems may initially seem counterintuitive, I encourage you to embrace it. Maybe you will take some time at first, quite possibly even more time than coding itself, but as you practice and improve this skill you’ll see yourself doing it faster and faster, and whenever you run into a complex system filled with intricate details, you'll be glad you fostered this ability. So don’t give up and keep drawing!&lt;/p&gt;

</description>
      <category>documentation</category>
      <category>productivity</category>
      <category>software</category>
      <category>systemdesign</category>
    </item>
  </channel>
</rss>
