Blog

iSAQB Software Architecture Gathering 2025​

Principal of the Atlantic Systems Guild
Published on September 22, 2025

Frameworks Done Right: Peter Hruschka on Documentation, Reuse, and Sharing Knowledge

An interview with Peter Hruschka

What are the characteristics that make a "good" framework? (You'll probably mention documentation, but what else?)

Frameworks (and libraries) are useful aids for developers to liberate them from (mostly technical) tasks. Therefore, a good framework should be easy to use and hard to misuse (similar to good interfaces). And yes: in order to make them easy to use, they should be well documented. For users of the framework, the documentation should cover everything a developer needs to know to properly integrate the framework into his/her own systems. For the developer of a framework, the same rules apply as for any system: Have enough documentation that future enhancements can be developed without lots of reengineering efforts of the existing framework.

Should frameworks be "invented" (from the drawing board) or "harvested" (extracted from concrete solutions)? If both, what is a healthy ratio?

Since most frameworks solve technical problems, I think they can be invented on the drawing board. Providing tools for building web applications, simplifying database interactions, helping to create user interfaces, or aiding in writing automated tests are well-understood topics.

However, if an organization develops multiple similar systems (or product families) in a specific domain, then there is a fair chance that domain-specific abstractions can be discovered and factored out into frameworks.

So, I would guess the ratio between technical frameworks and domain-specific frameworks is likely to be 80:20.

Would you generally encourage more people to harvest/invent, publish, and promote new frameworks from their work, or is framework engineering an exceptional thing to do?

Coming back to the observations above, I would not encourage organizations to go into the (commercial) framework business. Marketing frameworks should be left to companies specializing in such products (or open-source projects).

But every large IT organization should invest in discovering reusable ideas and factoring them out in form of frameworks and libraries – not with the intention to market them, but only to improve their inhouse effectiveness in product development instead of reinventing the wheel in every project.

Is using standard/established terminology a tool for tackling the abstractness of frameworks? arc42 is pretty widespread and brings some terminology with it. Are there other broadly accepted sources for well-understood general concepts?

arc42 is a generic template for all kinds of applications (including frameworks). While chapter 5 of arc42 (i.e., the building block view) is of central importance for most applications, it is not so important for framework users. Chapter 8 (cross-cutting concepts) plays a more important role for framework users.

Finding and documenting such cross-cutting concepts is still an art and requires abstraction skills from the framework developers. We advocate that the documentation of such concepts should not only identify their key abstractions, but also include very practical information like examples, prototypes, runtime scenarios, test cases with source code, etc.

Good documentation finds the right balance of textual & visual content, conceptual descriptions & very concrete instructions (and other tradeoffs). However, having access to an expert, interactive feedback, and active teaching are invaluable for adopting any technology (framework, library). What can framework authors do to cover this dimension?

Yes, correct. Having access to experts is definitely very helpful, instead of having documentation only. If no access is possible, the open-source initiative arc42 tries to help in many ways, especially with extensive published FAQS (faq.arc42.org), with lots of practical tips (docs.arc42.org).

Since developers learn best by copying from successful solutions, we also do publish complete system documentation about many different domains on Leanpub (https://leanpub.com/bookstore?search=arc42%20by%20example&type=all).

A third volume on frameworks and libraries is in the pipeline, adding to the first two volumes (on commercial systems and embedded real-time systems).