Generalize to Widen Impact

July 01, 2024

As a software engineering manager, I’ve come to appreciate the impact that clear, generalized, and reusable code can have on a project and its team. One of the core principles that I strive to instill in my team is the concept of “Generalize to Widen Impact.” This principle is about creating work that goes beyond the immediate needs of a project to benefit future endeavors and broader audiences. It’s about turning implicit knowledge into explicit, modular, and reusable components that others can understand and build upon.

Making Knowledge Explicit

One of the biggest challenges in software development is dealing with implicit knowledge—those unwritten understandings and assumptions that live in the minds of individual developers. When this knowledge isn’t documented, it can lead to bottlenecks and frustration, especially when team members leave or when new engineers join the project.

To combat this, I encourage my team to transition from implicit to explicit knowledge. This involves documenting not just the "what" of our code, but the "why" and the "how." For instance, when we make design decisions, it’s crucial to document the reasoning behind them. This helps the next engineer understand the context and rationale, making it easier for them to maintain or extend the system. I encourage the teams to think about documentation as a 'secret super power' that leverages the collective tribal wisdom of decisions past to inform and influence the current and future activities of the team. Share, share, and share some more in whatever ways make sense for your team.

Emphasizing Modularity and Reusability

Creating modular and reusable code is another key aspect of this principle. When we write code that is too tightly coupled or specific to a single use case, we limit its potential. By designing our systems to be modular, we make it easier to isolate and understand individual components. This not only aids in testing and debugging but also allows us to reuse these components in different contexts, saving time and effort in the long run.

For example, rather than hardcoding specific business logic directly into a function, we can abstract this logic into a separate, reusable module. This module can then be used across different parts of the application or even in different projects. This approach not only reduces redundancy but also ensures consistency and reliability across our codebase.

Doing this means teaching engineers and teams the value of looking for opportunities to do this while writing code and when performing a peer review on a pull request. Get people to ask: "Is the way that this code written ready for reuse?" and if not provide feedback to emphasize this principle when reviewing a PR.

Facilitating Clear and Transparent Documentation

Good documentation is the backbone of any successful project and I alluded to that above. As a manager, I encourage my team to produce clear and transparent documentation. This includes writing comprehensive README files, inline comments, and detailed API documentation. Documentation should be considered an integral part of the development process, not an afterthought. I also encourage to think about where the documentation should live, and sometimes it can be beneficial that it lives as close to the code as possible so that its maintenance is part of the code update process.

To foster this habit, I implement code review processes that include checks for documentation. We use tools that can help automate parts of this process, ensuring that our documentation is always up-to-date with the codebase. Using things like GitHub Copilot or other AI tools can also help to create a skeleton or outline of documentation that will accelerate the process of creation and maintenance. Additionally, I advocate for the use of documentation tools and platforms that make it easy for developers to create and maintain high-quality documentation. These tools should allow anyone to be able to read, revise, and contribute to the documentation that we create as a team.

Encouraging a Culture of Knowledge Sharing

Building a culture that values knowledge sharing is crucial. I encourage my team to participate in regular knowledge-sharing sessions. My current teams have a bi-monthly "How Something Works" session where they can present on topics or share insights from recent projects. This not only helps to disseminate knowledge but also fosters a sense of community and collaboration within the team. We also create 'guilds' that focus on cross-cutting areas of concern between teams in an effort to address technical debt, share knowledge of best practices for implementation, and build subject matter experts in each team who can in turn share knowledge with the team.

Leading by Example

As a manager, leading by example is essential. I make it a point to follow these principles in my own work. When I contribute to the codebase, I ensure that my code is well-documented, modular, and reusable. By doing so, I demonstrate the value of these practices and set a standard for the team to follow. I try to create documentation regularly, and share what I know both at a technical and a business process level. Transparency in communication and advocacy for the value of trying to think about how we 'widen the impact' is critical for the teams to feel that this is something you don't just tell them, but also try to do.

Supporting Continuous Improvement

Finally, I believe in the importance of continuous improvement. I regularly seek feedback from my team on how we can better incorporate the “Generalize to Widen Impact” principle into our work. We review our processes and tools to identify areas for improvement and invest in training and resources that help our engineers develop the skills needed to apply this principle effectively.

In conclusion, “Generalize to Widen Impact” is a principle that can significantly enhance the quality and longevity of our software. By making knowledge explicit, emphasizing modularity and reusability, facilitating clear documentation, encouraging knowledge sharing, leading by example, and supporting continuous improvement, we can create a work environment where this principle thrives. This not only benefits our current projects but also lays a strong foundation for future success.


Profile picture

Written by Blake Martin Software Engineering Manager You should follow them on Twitter