175: Balancing Documentation and Working Software

Expanding ideas through writing, exploring object-oriented principles for Software Architecture and balancing working software with documentation

Thank you for reading Snippets of Text. Snippets from media about tech, programming, parenting, and more. This is a preview of a post available exclusively to paying subscribers. You can get unlimited access to all articles by purchasing a subscription.

Unrelated: Unveiling New Ideas and Challenging the Status Quo

Masters use intuition, which springs from intense rational focus, to guide their reasoning. Consciousness has always been meant to connect us to reality; the ultimate distinction is between ourselves and the world. Mastery is not based on genius or talent; it requires time and intense focus on a particular field of knowledge. Connecting with your environment is the brain's most primitive and powerful form of mastery. It's essential to look beyond what's immediately in front of you and think ahead. Mastery isn't about genetics or luck; it's about pursuing your natural inclinations and following your deep desire.

As you share your work, you may become embarrassed of the work you've done in the past. This could be more encouraging and make you consider quitting altogether. Rather than taking it as a sign of mediocrity, please take it as a sign that you're learning and growing. This should be encouraging because you're never starting from scratch: You're always building on what came before. Creativity experts cultivate a growth mindset. A growth mindset is crucial for progressing as a creative individual.

True masters have undergone significant hardships to achieve their success. We must be open to criticism while also maintaining a level of detachment from the ideas of our mentors. Beware of those who praise or befriend you early on, as they may have ulterior motives. Emotional responses can reveal a lot about a person. To generate new ideas, one should consider anomalies - things that appear odd, absent, or defective.

Additionally, knowledge is complex; the more you learn, the more you realize the gaps in your understanding. These gaps are often apparent, and it becomes surprising that this is the first time anyone has explored them. Exploring these gaps can lead to discovering new and exciting ideas.

[^]: Mastery

Off Topic: Exploring Principles for Flexible Software Architecture

By adhering to the rules of clean coding and designing with reuse in mind, we can create flexible and maintainable software systems. The corresponding concrete implementations will also change when changing an abstract interface. Yet, changes to concrete implementations may only sometimes need interface modifications. The smallest entities deployed as part of a system are called components. Well-designed components are always deployable and developable, regardless of how they are deployed.

Object-Oriented Design aims to arrange dependencies to allow for easy future change. The critical thing here is experimentation. We don't want to make a decision forced by the tools we are using or by the pressure that's not necessary. The Single Responsibility Principle is about functions and classes—but it reappears in a different form at two more levels. At the level of components, it becomes the Common Closure Principle. 

A module should be responsible to one, and only one, actor. The SRP says to separate the code that different actors depend on. The behavior of a software artifact should be extendable without having to change that artifact. A good software architecture would reduce the changed code to the barest smallest. The OCP is one of the driving forces behind the architecture of systems. The goal is to make the system easy to extend without incurring a high impact of change. The behavior of the system encompasses the performance action of the software. It determines how the system will work and the various functions the system will be able to perform. Some systems are impossible to alter. They are structured so that there is a limit to the number of times they can be changed.

[^]: Clean Architecture: A Craftsman's Guide to Software Structure and Design

Current Work: Balancing Documentation and Working Software

Communication within organizations can often be unclear and confusing. It's best to start small and focus on a specific project to tackle this issue. To ensure progress, schedule weekly meetings to review progress at all stages. ADRs capture a set of forces and the single decision that responds to them. The decision is central, meaning specific points may appear in many ADRs (Architecture Decision Records). Each ADR is numbered and has a short noun phrase title. 

Thanks for looking at the free preview of Snippets of Text. Please consider subscribing to the paid version if you find my work helpful. This way, I can spend more time developing new ideas to share with you.