Mastering Software Architecture Documentation: 4 Techniques You Need to Know

[@abraham.sanchez]

Shoutout to you, Lucas. Your setup, the camera angles, how you play with those, and the content are really engaging! I have a couple of years of experience in software, not as much as you, but it's rare to see someone from our field be that confident talking in front of a camera or on stage! Congrats!🎉

[@My50c]

Thank you 🙏

[@mordel_]

I enjoy these partly because of the interaction between them. When you're making an ADR / RFC, you likely then have new content to use to update the C4 diagrams. And vice-versa, when you're writing an RFC, you draw on the C4 diagrams to provide context on what parts you're talking about.

[@My50c]

It depends from the RFC and if the team is using C4 model. I thought showing them as separated artifacts will allow people to combine them in the way they need/want Thanks for watching

[@ChrisMicallef]

This video is a perfect example how great content should be delivered and why the way things are presented is key.

[@My50c]

Thank you so much for your kind feedback 😍

[@Skuiggly]

Thank you for informing us of such useful tools! It was very nice to see RFCs used in a real environment though I wish there was more of that! If the tools are so great, you don’t have to tell us, show us!

[@My50c]

Thanks for the feedback 🙏 I will think about more content on that topic

[@Skuiggly]

@@My50c awesome! if you plan on making more informative videos like this i would love to see more in-depth how to "properly" employ ADR and RFC into an organisation! me and my team at a voluntary organisation at uni are managing our organisations web infra and developing a new website as the current codebase is pure legacy. we dont know why certain decisions were made, we don't have any rituals for changing our decisions, and we don't have an overview of how the current systems work without digging into the code we can barely read. thats why i want to learn more about these topics, as they seem like the perfect solution for our problems. i feel like theres a lot of theoretical content about software architecture, but not so much about how to put these techniques and patterns into practice. that could be a great market for you to capture! im sure you have a lot of knowledge and insight to share that could be both entertaining, informative and useful for lots of curious engineers :)

[@My50c]

@@Skuiggly sure, that's definitely a valid point. However the main issue is thinking that there is a solution that fits them all. Quite the opposite. In certain cases, like ADRs and RFCs, you can share best practices when to employ them in your software engineering flow. But it shouldn't be taken as a mantra. The software engineering practices changes a lot with the amount of people who are working on a single system and therefore it's important to balance your decisions. What large companies are doing are definitely different from what startups should do. Your context should dictate the way to build systems

[@RubenCasas]

Great content Luca! invaluable tools and explanation of these techniques... I am a huge fan of ADRs

[@My50c]

Thanks 🙏

[@theburningmonk]

Love the production value! The background and editing are looking great 👍

[@My50c]

Thanks a lot mate! 😍

[@azizsaya1]

useful info doesn't start until 06:18 🤷‍♂ but once it start this is some pretty valueable info 🤠

[@linointhecloud]

Great editing man! Love the background scene, looks cool 👍

[@My50c]

Thanks a lot 👍

[@garotohxc]

Amazing content and great editing!! Kudos!!!

[@My50c]

Thank you 🙏

[@SahilDaBoss]

Lucas, I am reading most of your post. But the video is little bit hard to understand. May be I am wrong but as English is my second language I can tell you the sentences are very close when you speak. No tone fluctuates between words that makes hard to understand. But I am still enjoying it with subtitle so all good. If you can improve it, it would be amazing. Thank you

[@My50c]

Thanks for the feedback

[@ZhekaMechsheryakov]

in you experience, if there are stakeholders who are not agree with an ADR, do you decline such recision? or you write up only "approved" ones

[@My50c]

A rejection is per se a decision. Therefore I'd gather the feedback regarding WHY the decision was rejected and if someone else will challenge the decision in the future, you will have historical data providing the context of the rejection. Bear in mind, ADRs are great also for re-evaluating decisions that in the past were taken. You can even create a mechanism inside your organisation where every X months you wanna revisit the decisions and make sure they are still accurate or revert some decisions based on new technologies available at that point in time for instance

[@dustsucker4704]

How would you Handle a two layer System like a webshop build in php with Page Generation and translation. And Javascript for Interaktion and updating data on the page?

[@My50c]

What about a server-side rendering approach?

[@MohamedWaheedAtef]

The sound effect you are using when a text is written is really bad, please change it, it is too abrupt, sharp and distracting, thanks for the video 🙏🏻

[@My50c]

Ok sorry to hear that, I'll be more mindful next time

[@0MegaJumper0]

Hi Luca, Thank you for the video, but I didn't enjoy it so much. First of all, a third of the video is spent on introduction, you only start discussing ADR on the 6th minute. Second, there is very little real content and a bit too much water in the talk. I already knew about ADR and RFC, so understand those were easier, but I struggled to understand the idea beyond event storming. It feels like you spend too much time on describing the same benefits of the documentation over and over for every documentation method. For my taste you are using too many adjectives like "powerful" instead of analysing the methods with pros and cons. Hope this helps. Thank you for your work and for the email newsletter (this is how I found your video).

[@My50c]

thanks for your honest feedback, I really appreciate it. I got a more in depth discussion on Event Storming for the near future, so keep an eye on the channel and the newsletter