Against the odds: 12 women who beat bias to succeed in science

Mike's Notes

Recently, I read the biography of Katlin Karikó, an incredible woman scientist from Hungary who devoted her entire working life to finding a way to get cells to heal themselves using their cellular machinery (mRNA, etc.).

"Katalin Karikó has had an unlikely journey. The daughter of a butcher in postwar communist Hungary, Karikó grew up in an adobe home that lacked running water, and her family grew their own vegetables. She saw the wonders of nature all around her and was determined to become a scientist. That determination eventually brought her to the United States, where she arrived as a postdoctoral fellow in 1985 with $1,200 sewn into her toddler’s teddy bear and a dream to remake medicine. 

Karikó worked in obscurity, battled cockroaches in a windowless lab, and faced outright derision and even deportation threats from her bosses and colleagues. She balked as prestigious research institutions increasingly conflated science and money. Despite setbacks, she never wavered in her belief that an ephemeral and underappreciated molecule called messenger RNA could change the world. Karikó believed that someday mRNA would transform ordinary cells into tiny factories capable of producing their own medicines on demand. She sacrificed nearly everything for this dream, but the obstacles she faced only motivated her, and eventually she succeeded.

Karikó’s three-decade-long investigation into mRNA would lead to a staggering achievement: vaccines that protected millions of people from the most dire consequences of COVID-19. These vaccines are just the beginning of mRNA’s potential. Today, the medical community eagerly awaits more mRNA vaccines—for the flu, HIV, and other emerging infectious diseases.

Breaking Through isn’t just the story of an extraordinary woman. It’s an indictment of closed-minded thinking and a testament to one woman’s commitment to laboring intensely in obscurity—knowing she might never be recognized in a culture that is driven by prestige, power, and privilege—because she believed her work would save lives."

Apart from her heroism in the face of overwhelming odds, what struck me was her description of the lack of decent childcare in the US, compared to Hungry,  as a barrier for women in the workforce.

When I get Ajabbi up and humming, one of the first things I will organise is to provide free, unlimited, quality childcare so women with kids can work. All work at Ajabbi needs to be family-friendly.

I am looking for the Katlin's of this world.

The article below is reprinted from Nature and is a book review.

Katlin Karikó

Resources

Repository

  • Home > Ajabbi Handbook > Ajabbi Research > Staff > Childcare

Last Updated

  • 05/03/2025

Against the odds: 12 women who beat bias to succeed in science

By: Georgina Ferry
Nature: 03 March 2025

A book deftly highlights how women have been considered unsuitable as researchers for reasons other than their ability and commitment.

Against the Odds: Women Pioneers of Science John Gribbin and Mary Gribbin Icon Books (2025)

What is it with toilets? In domestic households, men and women use the same ones without a fuss, but at some point in history it became etiquette for toilets in workplaces to be segregated. And in supposedly male environments, it meant that there simply weren’t any for women. It then became absurdly easy to use the lack of appropriate toilets as an excuse to deny women a role in those environments or, if they did take a job there, to make their lives difficult.

Toilets come up in several of the 12 stories selected for John and Mary Gribbin’s gallery of female pioneers in science, Against the Odds. In the opening years of the twentieth century, physicist Lise Meitner, banished to a basement because she wasn’t allowed to work in the chemistry laboratories of what was then the Royal Friedrich Wilhelm University of Berlin, had to use the toilets in a neighbouring restaurant. During the 1950s, computer pioneer Lucy Slater, while developing the operating system for an early computer at the University of Cambridge, UK, smashed the sanitary equivalent of a glass ceiling by simply using the men’s toilet (singing loudly to signal her presence). And in 1964, Vera Rubin became the first female astronomer who was officially allowed to use the big telescopes at the Mount Wilson and Palomar observatories in California, overturning a ban that had been partly, but explicitly, based on the lack of a women’s toilet.

Science trailblazers

Compared with unequal pay for the same work, the reality of men with fewer qualifications being promoted ahead of them and the frank refusal to recognize that a married woman with children might be capable of a career, the toilet issue was probably a trivial annoyance to these women. But it symbolizes how, for centuries, women have been considered unsuitable as scientists for reasons that have nothing to do with their ability or commitment.

The Gribbins’ aim is to “highlight the achievements of women who overcame the odds and achieved scientific success ... as society changed over about 150 years”. They don’t justify their selection, other than to note that the women featured (ordered by year of birth) collectively cover the period. But it is startling that physicist Chien-Shiung Wu is the only scientist who is not white or born in a Western country (and she spent most of her career in the United States). The ‘hidden figures’ — African American women who calculated trajectories for early NASA space missions — remain hidden. Many girls won’t find a role model who looks like them in the book.

With that caveat, the Gribbins tell the stories with an adroit mix of anecdote and exposition. There is a bias towards physical sciences, perhaps reflecting John Gribbin’s background in astrophysics. Some of those featured (such as crystallographer Rosalind Franklin) are close to being household names, others (geophysicists Eunice Newton Foote and Inge Lehmann) are much less familiar. Three of the women (chemists Irène Joliot-Curie and Dorothy Crowfoot Hodgkin and geneticist Barbara McClintock) won Nobel prizes; two (Meitner and Wu) should have done.

Some of the women were less celebrated during their lifetimes. It took 100 years for historians to uncover the work done by Foote, as a wealthy ‘lady amateur’ working in her home lab in New York state. She demonstrated that water vapour and carbon dioxide absorbed energy from sunlight and so could increase global temperatures. Her 1856 paper included the statement that if “the air had mixed with it a larger proportion [of CO2] than at present, an increased temperature ... would have necessarily resulted”. Three years later, John Tyndall, unaware of Foote’s work, performed the experiments that are generally credited with establishing the nature of the ‘greenhouse effect’.

Equal partners?

Foote was a suffragist and abolitionist who married an equally enlightened husband, working together at the lab bench. Men have an important role in these women’s accounts, as enablers or obstructors — sometimes both. Meitner’s work on radiation involved a decades-long collaboration with chemist Otto Hahn. The relationship seems to have been fruitful and harmonious, and Meitner gradually overcame institutional prejudice to achieve professional recognition. But the advent of Nazism led her to flee to Stockholm, where she came up with the idea of nuclear fission in conversation with her nephew Otto Frisch. After correspondence with Meitner, Hahn confirmed its existence experimentally and he alone was awarded the chemistry Nobel prize in 1944. Far from insisting — as Pierre Curie had done for his wife and co-worker Marie — that the prize should be shared with Meitner, he allowed a narrative to develop that she had been his assistant, when the opposite was nearer the truth.

As a biographer myself (disclosure — the Gribbins’ chapter on Crowfoot Hodgkin draws on my book, with attribution), I can’t stress too strongly the importance of the formative years in determining whether women pursue scientific careers. German mathematician Emmy Noether was typical of this group in having highly academic parents — her father was also a distinguished mathematician — who paid for her to have private tuition in the subject at the beginning of the twentieth century, when German universities were not open to women. A rearguard attempt to stop her from gaining a university position made the extraordinary claim that “a woman ‘is unsuitable for regular instruction of our students because of the phenomena connected with the female organism’”. Growing up in a family that says ‘yes you can’ in a society that is still saying ‘no you can’t’ makes all the difference in imparting the sense of agency that fuels a determination to continue against the odds.

Motherhood might be seen as one of the biggest obstacles, once institutional sexism has been excluded, although the two cannot be disentangled completely. In 1923, Leslie Comrie wrote a letter in support of fellow astronomer Cecilia Payne-Gaposchkin, who was a student at the University of Cambridge, UK, at the time. Payne-Gaposchkin wanted to work at the Harvard College Observatory in Cambridge, Massachusetts, and in his letter, Comrie assured the observatory’s director that “she would not want to run away after a few years training to get married”. She didn’t run away but, some ten years later, did marry émigré Russian astronomer Sergei Gaposchkin, and they had three children with no noticeable effect on her prodigious research output on stellar evolution and the composition of stars. Payne-Gaposchkin and Crowfoot Hodgkin share the distinction of having given prestigious public lectures while pregnant (and in Crowfoot Hodgkin’s case, under her maiden name of Crowfoot).

Half of those featured in the book became mothers; others, such as Lehmann and McClintock, made a nun-like commitment to science above all else. Yet they all had a passion for discovering more about the natural world, and a joy in doing so, that enabled them to overcome all obstacles. Historians might frown on collections, such as Against the Odds, that put a spotlight on individuals. But they serve to remind young women who find it hard to have a scientific career that this has often been the case, and that hanging on to that quest for joy is worth it in the end.

As noted in Against the Odds, Nobel-prizewinning physicist Richard Feynman’s sister Joan decided to become an astrophysicist after he gave her an astronomy textbook containing a graph credited to Payne-Gaposchkin. It gave her the ammunition she needed to defy her mother and insist that girls could do physics. The need for such ammunition is less today than it was in 1941, but it hasn’t disappeared.

Creating an environment for plug-ins

Mike's Notes

Here are my rough ideas about how to create an environment in Pipi 9 for plug-ins.

I want to reduce Pipi to its essential and closed core, and the remainder will be turned into open-source plug-ins available on GitHub. The community could then create other plug-ins and modules to extend the platform.

I would like to talk with people who have done something similar.

Resources

References


Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

11/05/2025

Creating an environment for plug-ins

By: Mike Peters
On a Sandy Beach: 04/03/2025

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

From Wikipedia - "In computing, a plug-in (or plugin, add-in, addin, add-on, or addon) is a software component that extends the functionality of an existing software system without requiring the system to be re-built. A plug-in feature is one way that a system can be customizable.

Applications support plug-ins for a variety of reasons including:

  • Enable third-party developers to extend an application
  • Support easily adding new features
  • Reduce the size of an application by not loading unused features
  • Separate source code from an application because of incompatible software licenses
..."

I have been putting off creating a plug-in environment for Pipi 9 because it wasn't an urgent task.

However, recently, a representative of a large software company contacted Ajabbi about embedding their product on ajabbi.com web pages, which raised the issue of plug-ins. We talked, and now they are considering it.

I might have a first plugin to build, so I better figure out how to do this. :)

I am now working this out by the seat of my pants, and things will no doubt change a lot.

I did a lot of investigating when working on Pipi 6 (2017-2019), and I liked how OpenERP (Now Odoo) enabled community-sourced extensions (they call them addons) to its open SaaS product.

The Odoo addons are packaged using a sensible standard format.

  • manifest_py
  • readme
  • controllers/
  • data/
  • demo/
  • doc/
  • i18n/
  • models/
  • report/
  • security/
  • static/
  • tests/
  • tools/
  • views/
  • wizard/

Plug-in package

A package structure similar to Odoo and simple industry standard file formats would work, packaged in a zip file and including the following.

  • Name
  • Description
  • Author/developer
  • Icon
  • Manifest file (XML)
  • Sample data (SQL)
  • Language strings of any other language mapping to the base English string (CSV)
  • etc

Plug-ins and modules are quite different.

SaaS Module

  • SaaS applications are built out of reusable modules.
  • The admin web UI should be the only thing required to add or remove modules (tick boxes).
  • Modules follow domain-driven-design (DDD) principles.
  • Have an MCV architecture.
  • Examples:
    • Assets
    • Invoices

SaaS Simple Plug-in

  • Simple Plug-ins add simple UI functionality to a SaaS application and usually involve HTML.
  • Simple forms are used to add plug-ins.
  • CMS Examples:
    • Embed Google Map
    • Embed ESRI Map
    • Embed Mathematica Notebook
    • Embed Jupyter Notebook
    • Embed complex Java object

SaaS Complex Plug-in

  • Complex Plug-ins can work with third-party applications using methods such as databases, APIs, scripting, XML, and JSON.
  • The DevOps Engine (dvp) is required to configure integration.
  • Examples:
    • Office 365
    • Google Workplace
    • Zoho
    • Odoo

Pipi Plug-in

  • Pipi Plug-ins extend Pipi by adding 3rd-party software using wrapper and configuration settings.
  • The DevOps Engine (dvp)  is required to configure integration.
  • The plug-ins can interact fully with the engines and other Pipi objects.
  • Examples:
    • Docker
    • Database, e.g. semantic, graph, document
    • Another computer language, e.g. Prolog
    • Another API type, e.g. SOAP
    • Azure platform config
    • AWS platform config
    • GCP platform config
    • WolframAlpha
    • ESRI ArcGIS

Engines

  • The Plug-in Engine (plu) to register plug-ins is now being built.
  • The Module Engine (mdl) registers all modules.

Customer DevOps

Mike's Notes

Here are my working notes from day 9 of building the DevOps Engine for Pipi 9. 

Over the weekend, I attended an excellent film script workshop, but managed to work on the DevOps Engine when I wasn't supposed to. Often, I get more done by relaxing and not thinking about a problem. Then, these new ideas start interrupting.

Resources

References


Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

11/05/2025

Customer DevOps

By: Mike Peters
On a Sandy Beach: 03/03/2025

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

Today, I enabled a separate DevOps Engine for my first customer. Since they will use a multi-tenanted SaaS application, their DevOps engine will also be multi-tenanted.

In this case, their DevOps Engine setup is more about feature requests, customer support, configuration management and automated builds.

Creating a second, customised DevOps Engine helped clarify other practical problems that apply more broadly to building a front-end.

Steps

  • DevOps steps use standard workflow processes.
  • Moving between these steps uses transition conditions that can change states and trigger other asymmetric processes.

Multi-tenancy

By asking how the chosen tenancy model modified the Pipi instance, I clarified some assumptions and operational rules that result from using multi-tenancy rather than sole tenancy.
  • Multi-tenanted SaaS applications for SMEs will use a multi-tenanted Pipi in the back end, which allows less customisation.
  • Sole-tenanted SaaS enterprise applications will use a sole-tenanted Pipi in the back end, allowing more customisation.

Deployment

  • I figured out a simple way to automatically remove a customer deployment in a multi-tenanted situation, allowing Pipi to close an account.

History of DevOps

Mike's Notes

Some helpful background history to give context. Written by Ian Buchanan, Principal Solutions Engineer, Atlassian

Resources

References


Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

02/03/2025

    History of DevOps

    By: Ian Buchanan
    Atlassian: 

    How development and operations teams came together to solve dysfunction in the industry.

    Despite the rise of agile methodology, development and operations teams remained siloed for years. DevOps is the next evolution of collaboration tools and practices to release better software, faster.

    Bringing development and IT teams together

    The DevOps movement started to coalesce some time between 2007 and 2008, when IT operations and software development communities raised concerns what they felt was a fatal level of dysfunction in the industry.

    They railed against the traditional software development model, which called for those who write code to be organizationally and functionally apart from those who deploy and support that code.

    Developers and IT/Ops professionals had separate (and often competing) objectives, separate department leadership, separate key performance indicators by which they were judged, and often worked on separate floors or even separate buildings. The result was siloed teams concerned only with their own fiefdoms, long hours, botched releases, and unhappy customers. Surely there’s a better way, they said. So, the two communities came together and started talking – with people like Patrick Debois, Gene Kim, and John Willis driving the conversation.

    What began in online forums and local meet-ups is now a major theme in the software zeitgeist, which is probably what brought you here! You and your team are feeling the pain caused by siloed teams and broken lines of communication within your company.

    You’re using agile methodologies for planning and development, but still struggling to get that code out the door without a bunch of drama. You’ve probably heard a few things about DevOps and the seemingly magical effect it can have on teams: Nearly all (99%) of DevOps teams are confident about the success of their code that goes into production, in a survey of 500 DevOps practitioners conducted by Atlassian¹. 

    However, DevOps isn’t magic, and transformations don’t happen overnight. The good news is that you don’t have to wait for upper management to roll out a large-scale initiative. By understanding the value of DevOps and making small, incremental changes, your team can embark on the DevOps journey right away.

    Going beyond agile

    DevOps touches every phase of the development and operations lifecycle. From planning and building to monitoring and iterating, DevOps brings together the skills, processes, and tools from every facet of an engineering and IT organization.

    Agile methodologies help teams plan and produce by breaking work down into manageable tasks and milestones. Agile relies on sprints, backlogs, epics, and stories to assign work to skilled team members, adjust timelines when necessary, and deliver quality products and services to customers. Read more about agile.

    Continuous integration and delivery: Continuous integration and delivery is a cornerstone of DevOps practices that relies on automating the merging and deployment of code. Traditional development methods require engineers to manually update changes in the codebase, with additional manual checks to ensure quality code is ready to ship into production. Deployments are scheduled with weeks- or months-long delays to remove the likelihood of bugs or incidents. DevOps practices remove these delays by automating the merging, testing, and deployment functions. High-performing teams use CI/CD to reduce their deployment frequency from every few months to multiple times each day. Read more about CI/CD.

    Git repositories and workflows enable the automation and version control capabilities that are foundational to DevOps practices. Because Git is distributed, operations such as commit, blame, diff, merge, and log happen faster. Git also supports branching, merging, and rewriting repository history, which enables powerful workflows and tools. Read more about Git.

    IT service management is the process IT teams use to manage the end-to-end delivery of IT services to customers. This includes all the processes and activities to design, create, deliver, and support IT services. The core concept of ITSM is the belief that IT should be delivered as a service, which goes beyond basic IT support. ITSM teams oversee all kinds of workplace technology, ranging from laptops, to servers, to business-critical software applications. Read more about ITSM.

    Incident management teams respond to an unplanned event or service interruption and restore the service to its operational state. In a “you build it, you run it” model, developers partner with operations to reduce the likelihood of an incident occurring, and also reduce the mean time to recovery when an incident happens. Read more about incident management.

    State of DevOps

    Organizations and teams continue to adopt DevOps practices and tools. In a survey of 500 DevOps practitioners, Atlassian found that 50% of organizations say they’ve been practicing DevOps for more than three years.

    Unfortunately, despite agreement on the definition of DevOps and the benefits of implementing DevOps practices, organizations and teams still struggle to fulfill the promise of DevOps. Teams must focus on continuous feedback, iteration, and improvement to deploy better and faster to meet customers' needs.

    You can learn DevOps best practices with our Beginner's guide to DevOps. To put DevOps into practice, we recommend trying Open DevOps, which provides everything teams need to develop and operate software. Teams can build the DevOps toolchain they want, thanks to integrations with leading vendors and marketplace apps. Try it now.

    5 Authentication Features You Should Know

    Mike's Notes

    In last week's issue of Level-up Coding engineering newsletter, there was this article by Nikki Siapno, Engineering Manager at Canva and Co-Founder of Level Up Coding.

    "Level up your engineering and system design skills. Join the growing community of engineers who prefer our visual approach to software engineering." - Level Up Coding

    Resources

    References


    Repository

    Home > Ajabbi Research > Library > Subscriptions > Level Up Coding

    Last Updated

    01/03/2025

      5 Authentication Features You Should Know

      By: Nickki Siapno
      LinkedIn: 20/02/2025

      Authentication isn’t just about logging in.

      It involves multiple layers of security, user experience, and compliance. 

      Here are five auth features you should consider adding to your applications to enhance security and provide a seamless user experience:

      𝟭) 𝗟𝗼𝗴𝗶𝗻 & 𝗥𝗲𝗴𝗶𝘀𝘁𝗿𝗮𝘁𝗶𝗼𝗻

      Includes secure credential storage, password hashing, and customizable user flows for seamless onboarding.

      𝟮) 𝗦𝗶𝗻𝗴𝗹𝗲 𝗦𝗶𝗴𝗻-𝗢𝗻 (𝗦𝗦𝗢)

      Lets users log in once and access multiple apps via OAuth 2.0, OIDC, or SAML.

      𝟯) 𝗠𝘂𝗹𝘁𝗶-𝗙𝗮𝗰𝘁𝗼𝗿 𝗔𝘂𝘁𝗵𝗲𝗻𝘁𝗶𝗰𝗮𝘁𝗶𝗼𝗻 (𝗠𝗙𝗔)

      Adds a second layer of security with TOTP codes, biometrics, or push notifications.

      𝟰) 𝗣𝗮𝘀𝘀𝗸𝗲𝘆𝘀 (𝗪𝗲𝗯𝗔𝘂𝘁𝗵𝗻)

      Passwordless authentication using biometrics and device-native security for a seamless login experience.

      𝟱) 𝗠𝗮𝗴𝗶𝗰 𝗟𝗶𝗻𝗸𝘀

      One-time login links sent via email, eliminating the need for passwords while enhancing UX.

      𝗛𝗼𝘄 𝗱𝗼 𝘄𝗲 𝗶𝗺𝗽𝗹𝗲𝗺𝗲𝗻𝘁 𝘁𝗵𝗲𝘀𝗲 𝗳𝗲𝗮𝘁𝘂𝗿𝗲𝘀?

      • Building from scratch is time-intensive, requires expertise in security, UI/UX, email systems, and compliance.
      • That's why 𝗮𝘂𝘁𝗵 𝗽𝗿𝗼𝘃𝗶𝗱𝗲𝗿𝘀 (CIAM solutions) like FusionAuth are so popular.
      • They 𝗮𝗯𝘀𝘁𝗿𝗮𝗰𝘁 𝗮𝘄𝗮𝘆 𝘁𝗵𝗲 𝘄𝗼𝗿𝗸 𝘄𝗵𝗶𝗹𝗲 𝗽𝗿𝗼𝘃𝗶𝗱𝗶𝗻𝗴 𝘂𝘀 𝗳𝘂𝗹𝗹 𝗰𝗼𝗻𝘁𝗿𝗼𝗹.
      • FusionAuth is an auth provider that I've been very impressed with. They provide:
      • 𝗖𝗼𝗺𝗽𝗿𝗲𝗵𝗲𝗻𝘀𝗶𝘃𝗲 𝗮𝘂𝘁𝗵𝗲𝗻𝘁𝗶𝗰𝗮𝘁𝗶𝗼𝗻 & 𝘀𝗲𝗰𝘂𝗿𝗶𝘁𝘆 → Covers authentication, authorization, user and org management, and threat detection.
      • 𝗦𝗲𝗹𝗳-𝗵𝗼𝘀𝘁 𝗼𝗿 𝘂𝘀𝗲 𝘁𝗵𝗲𝗶𝗿 𝗰𝗹𝗼𝘂𝗱 → Unlike many providers, FusionAuth lets you develop, test, and deploy locally or in the cloud.
      • 𝗙𝗲𝗮𝘁𝘂𝗿𝗲-𝗿𝗶𝗰𝗵 𝗳𝗿𝗲𝗲 𝘁𝗶𝗲𝗿 → Generous free plan to get started without commitment.

      DevOps Pipeline

      Mike's Notes

      Here are my working notes from day 6 of building the DevOps Engine for Pipi 9.

      Resources

      References

      • Reference

      Repository

      • Home > Ajabbi Research > Library >
      • Home > Handbook > 

      Last Updated

      17/05/2025

      DevOps Pipeline

      By: Mike Peters
      On a Sandy Beach: 28/02/2025

      Mike is the inventor and architect of Pipi and the founder of Ajabbi.

      Today, I added pipelines to the initial DevOps Engine data model. 

      Pipeline

      In Pipi 9, a DevOps pipeline is a set of automated processes and tools that enable team members and Pipi, the robot, to collaborate on deploying data model changes, workflows, code, experiments, algorithms, engine mixtures, digital twin, etc., to the live production environment that is Pipi.

      Steps

      I also enabled any DevOps team to select what steps to use in a pipeline from a library of steps.

      • Each step has configurable properties.
      • The set of steps can be different for each pipeline.
      • Different team structures could need different step configurations.
      • For example, Atlassian has these steps.
        • Discover
        • Feedback


        DevOps Engine

        The DevOps Engine can be used in different situations, including:
        • Internally on Pipi.
        • By those who create and deploy enterprise SaaS applications.
        • Providing support to paying customers.
        • Etc.

        WBS

        Because of dependencies, every task has a Work Breakdown Structure (WBS). They are all part of a larger whole. However, the tasks are being done out of order because it is easier. In the end, they all need to be done. This use of WBS needs more experimentation and thinking.

        Next steps

        The published web page roadmap has been imported as data into the DevOps database. After some tweaking at both ends, it worked. Tasks can now be edited. I just need the Render Engine to republish the web page whenever an edit is made or automation runs.

        I would like to talk to people who have experience using DevOps tooling.

        The Ultimate Guide To Software Architecture Documentation

        Mike's Notes

        I discovered a link to this excellent article in the latest Quastor engineering newsletter. Patrick Roos's article has valuable insights despite its unstructured, rambling nature (at least for me). So, I have heavily edited down what he wrote and shifted most of the links to the references. His other articles are well worth reading.

        Resources

        References

        • Reference

        Repository

        • Home > Ajabbi Research > Library >
        • Home > Handbook > 

        Last Updated

        17/05/2025

        The Ultimate Guide To Software Architecture Documentation

        By: Patrick Roos
        Quastor: 02/01/2023

        This guide shows you how to write, structure, visualize and manage software architecture documentation in a lean way using appropriate documentation tools.

        Table of Contents

        • Why should we document software architecture?
        • How should we structure software architecture documentation?
        • How should we visualize software architecture?
        • How do we write and manage software architecture documentation?
        • Why should we document software architecture?

        An often expressed opinion about software architecture documentation in "agile" teams is:

        "The code documents the system. We don't need any further documentation.

        But this statement is only half the truth. There are several questions that remain unanswered in the code.

        • What are the goals of the system?
        • What are the non-functional requirements?
        • What are the architectural decisions and their arguments?

        As Simon Brown has correctly pointed out:

        "The code doesn't tell the whole story.

        Long story short: You should document the software architecture of your system.

        Take a look at the goals you should fulfil with your documentation, and you'll understand why.

        Goals of software architecture documentation

        There are three goals that your software architecture documentation should fulfil.

        Software architecture documentation creates a common understanding

        Software architecture documentation should at least support the development team, for example, when a new team member starts.

        Let's take the onboarding example, a new team member has a lot of questions:

        • Where can I find an overview of the system's building blocks?
        • Why are you using Angular and not React? Why are you using Hibernate and not jOOQ?
        • Where and how is the system deployed?
        • Are there any conventions I need to be aware of?

        This brings us to the first goal of software architecture documentation:

        Software architecture documentation creates a common understanding of the solution behind the system for various stakeholders

        There are usually many different stakeholders interested in different aspects of our system: Software Architects, Software Engineers, Ops, Support, Testing, POs, Project Managers, SMEs, Business Sponsors and so on.

        You can create different views of your system's architecture by developing a common understanding of your system's software architecture.

        With this understanding, the various stakeholders can evaluate the underlying software architecture from their perspective.

        In this way, we can concretize the goal described above with the evaluation part:

        The documentation makes it possible to evaluate the software architecture from the perspective of the various stakeholders

        Software architecture documentation allows your stakeholders to judge whether the system is achieving the goal, since they often can't dive into the code.

        With good architecture documentation, they can answer the following questions:

        • Does the chosen architecture fit the solution?
        • Is the architecture appropriate?

        In this way, architectural documentation often prevents other goals, constraints, and non-functional requirements from creeping in.

        Let me give a practical example here.

        I've often heard from various stakeholders: "The system must be fast."

        But what does that mean?

        As a software architect, you have to turn these expectations into concrete quality goals, i.e., non-functional requirements with supporting quality scenarios. You record these quality goals in the architecture documentation, which in turn helps your team to implement the solution with the agreed non-functional requirements.

        Software architecture documentation supports architectural work

        Software architecture documentation supports team work

        Software architecture is a team effort, so it's most important that the software architecture documentation supports your team effort.

        As a team member, it's important to actively know (and pass on to new team members) the goals, constraints, and non-functional requirements within the team. This information is often very important in team architecture workshops.

        It's important to make understandable and comprehensible architecture decisions. Nothing is more annoying than not knowing why you decided the way you did.

        Software architecture documentation guides the development team in implementing new product features

        Documenting software architecture helps the entire development team implement the solution.

        • What constraints do I need to consider?
        • Which non-functional requirements do I need to test?
        • Which overarching concepts do I need to follow?
        • Are there architectural decisions I need to consider when implementing a particular feature?

        Software architecture documentation supports the communication with external stakeholders

        A large part of software architecture work is communication. In particular, communication with stakeholders is key to effective and focused discussion outcomes.

        Good software architecture documentation supports communication with external stakeholders. It contains different and stakeholder-appropriate views of the software architecture.

        Recommendations:

        1. Communication Patterns: A Guide for Developers and Architects by Jacqui Read
        2. Documenting Software Architectures: Views and Beyond by Paul Clements et al.
        3. Software-Architekturen dokumentieren und kommunizieren (German) by Stefan Zörner

        How should we structure software architecture documentation?

        An proven approach to structuring software architecture documentation is the arc42 template.

        What is the arc42 template?

        • arc42 provides a template for documenting and communicating software and system architectures.
        • arc42 is based on practical experience of many systems in various domains, from information and web systems, real-time and embedded to business intelligence and data warehouses. 
        • arc42 supports arbitrary technologies and tools.
        • arc42 is completely process independent and is particularly well suited for lean and agile development approaches.
        • arc42 is open source and can be used free of charge in both the commercial and private sectors.
        • arc42 is available in several languages.
        • arc42 is available in different formats like .adoc, .docx, .rst, .md, .tex, ...

        How is the Software Architecture according to the arc42 template structured?

        The following figure shows the resulting structure of the arc42 template.


        The structure of the arc42 template (Source)

        Good examples of an arc42 documentation

        • HTML Sanity Checker (HtmlSC) Architecture Documentation (Gernot Starke)
        • HTML Sanity Checker (HtmlSC) shall support authors creating digital formats
        • with hyperlinks and integration of images and similar resources.
        • DokChess (Stefan Zörner)
        • DokChess is a fully functional chess engine.
        • Gradle as an example for arc42 (Stefan Zörner) 🇩🇪
          Gradle automates the building, testing and delivery of software.

        Are there any possible pitfalls in the handling with arc42?

        Upfront document everything

        Don't document everything in advance. Think of the arc42 template as a cabinet for documentation. You put something on a shelf as you work on it. This is how software architecture documentation emerges, evolves, and stays current.

        Don't includes Tutorials or Q&A sections

        The most important thing in arc42 is the structure. The structure doesn’t provide a space for guides or Q&A sections.

        Don't put any specific things like customer names or similar

        Don't write customer-specific things in the software architecture documentation, unless your building blocks are structured in a customer-oriented way.

        Alternative documentation and structuring approaches

        There are some alternative structuring and documentation approaches.

        • Recommended Practice for Architectural Description of Software-Intensive Systems (IEEE 1417)
        • Documenting Software Architecture (SEI)
        • Software Architecture for Developers (Simon Brown)

        Recommendations:

        • arc42 by Example by Gernot Starke and Ralf D. Müller
        • arc42 in Aktion (German) by Gernot Starke and Peter Hrschuka

        How should we visualize the software architecture?

        The C4 model is a good approach to obtain a common set of abstractions. It's an abstraction-first approach and is notation independent.

        The C4 model looks at the static structures of a software system in terms of containers, components and code. And people use the software systems we build.



        Abstractions of the C4 Model (Source)

        What is a software system in C4?

        A software system is the highest level of abstraction and describes something that adds value to its users, whether they are human or not.

        What is a Container in C4?

        A container (not Docker!) is a separately deployable / executable thing.

        What is Component in C4?

        A component is a grouping of related functionality encapsulated behind a well-defined interface. If you're using a language like Java or C#, the easiest way to think of a component is that it's a collection of implementation classes behind an interface.

        What are the core views of C4?

        With these abstractions, we can create a context view (Level 1), a container view (Level 2), a component view (Level 3) and a code view (Level 4).



        The four levels of the C4 Model. Each level has a different target audience (Source)

        Level 1: System Context Diagram

        The following illustration shows the system which is embedded in its context.



        A system context diagram (Source)

        Level 2: Container Diagram

        If we zoom into the system (the internet banking system in the figure above), we get the container view of this system.

        Each of these containers is separately deployable.



        A container diagram (Source)

        Level 3: Component Diagram

        If we want to take a look inside a specific container, like the API application, we get the component view of that container.



        A component diagram (Source)

        Level 4: Code

        If we go deep into a particular component, we arrive at a "code" view.



        Level 4: Code Diagram (Source)

        This can be a class diagram. But you can often generate this kind of view by an idea, if necessary.

        Is the C4 model compatible with arc42?

        Yes, arc42 and C4 can be used complementarily.

        The C4 diagrams are relevant in the following arc42 chapters:

        • C4 System Context diagram can be placed in arc42 chapter 3 "Context and Scope"
        • C4 Container Diagram can be placed in arc42 Chapter 5 Building Block View (Level 1)
        • C4 Component Diagram can be placed in arc42 Chapter 5 Building Block View (Level 2)
        • Code Diagram can be placed in arc42 Chapter 5 Building Block View (Level 3)

        Besides the C4 diagrams presented above, there are some additional diagrams of C4 that can be inserted into arc42.

        • C4 Dynamic Diagram can be placed into arc42 Chapter 6 Runtime View
        • C4 Deployment Diagram can be placed into arc42 Chapter 7 Deployment View

        Recommendations:

        • Software Architecture for developers by Simon Brown
        • The C4 model for visualizing software architecture by Simon Brown

        How do we write and manage software architecture documentation?

        As with any software, there are requirements for technical documentation. Gernot Starke has excellently documented these requirements in the following blog post:

        Principles of technical documentation

        By: Gernot Starke
        INNOQ

        This article collects fundamental requirements for technical documentation, especially software architecture documentation, together with ideas how to *satisfy* those.

        A summary of the documentation requirements can be seen in the following figure from the blog post above:



        All documentation requirements (Source)

        Meeting some of these requirements (e.g., req-7, req-9, req-10, and req-11) leads to the conclusion that we should treat the document as code "Documentation as Code" or "Docs-as-Code".

        What is "Documentation as Code" ?

        "Documentation as Code" means that your documentation process benefits from the same practices you use to develop successful software.

        Some of these practices are:

        • Storing content in a version control system
        • Separation of content, configuration, and presentation
        • Use of automation for compilation, validation, verification and publishing (CI/CD)
        • Reuse shared materials (DRY)
        • ...and use your IDE to write content ;-)

        With this technique we get some value out-of-the-box:

        • Structuring of the whole document into subdocuments
        • Restructuring of the documentation according to specific stakeholder
        • Reference images, not embedding
        • Simple versioning "handle documentation as code”
        • Format of the documentation content like source code
        • Documentation Reviews, pull requests, versioning through Git tooling
        • Conversion to various presentation formats like HTML5, PDF, DocBook, Confluence, ...



        Treat documentation like code in a common development workflow

        Recommendations:

        • Like Code by Anne Gentle

        Are there any recommended tools for Documentation as Code?

        In Documentation as Code we can distinguish the following process steps: Authoring (write, validate and preview the documentation content), Converting (documents to the pulication formats like HTML, DocBook, PDF, etc.), and Publishing (Build and deploy documentation artefacts). For each of these steps there are some tools that I can recommend to fulfil the process step.

        Authoring: AsciiDoc

        AsciiDoc is a plain text markup language for writing technical content. Use the AsciiDoc format to write your content.

        Convert: Asciidoctor

        Asciidoctor is a fast processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.

        Publish: Maven, Gradle, docToolChain

        docToolchain is a collection of scripts that makes it easy to create and maintain powerful technical documentation. Built on best-of-breed open source technologies, we deliver the best docs toolchain so you don’t have to.



        Available tasks of the docToolchain (Source)

        And what's about diagrams?

        Like documentation, you can treat diagrams like code.

        Diagrams as Code 1.0

        A classical approach to describe diagrams in text can be done with PlantUML, Mermaid or GraphViz.



        Describe a diagram with text in PlantUML

        These diagrams can be embedded directly into AsciiDoc content and converted with AsciiDoctor.

        [plantuml, target=diagram-classes, format=png]   

        ....

        class BlockProcessor

        class DiagramBlock

        class DitaaBlock

        class PlantUmlBlock


        BlockProcessor <|-- DiagramBlock

        DiagramBlock <|-- DitaaBlock

        DiagramBlock <|-- PlantUmlBlock

        ....

        PlantUML Code in AsciiDoc embedded

        Now let's combine diagrams as code and the C4 model. This brings us to Diagrams as Code 2.0.

        Diagrams as Code 2.0

        What if we could describe our C4 model in text form and generate the C4 diagrams directly?

        This is where Structurizr comes in. It brings diagrams as code into a new dimension - Diagrams as Code 2.0.

        With the Structurizr DSL we can describe the Software with the C4 abstractions.



        Structurizr DSL Example (Source)

        After describing the C4 model of our software system, we can create all defined views directly (with different representations).



        Awesome, isn't it?

        By the way: Simon Browns gave a great talk about diagrams as code 2.0 with Structurizr.

        Combine everything together

        Now you have the whole toolbox for software architecture documentation:

        • Structure it with arc42
        • Describe and visualize it with the C4 model
        • Treat your documentation and diagrams like code with AsciiDoc, AsciiDoctor, docToolChain and Structurizr
        • ...and integrate it into your development workflow.

        Combine everything together and get a powerful software architecture documentation

        I've created an example repository where I've brought all these techniques and technologies together. Check it out.

        I've also created a corresponding YouTube video that explains this example project step by step.

        Further supporting software architecture documentation tools

        • D2 Lang
        • Diagrams
        • Kroki
        • Terrastruct
        • Context Mapper
        • Spring Modulith

        All Documentation as Code Tools can be found under the following link 👇

        Recommended Software Architecture Documentation Books

        • Software-Architekturen dokumentieren und kommunizieren (German) von Stefan Zörner
        • arc42 by Example by Gernot Starke and Ralf D. Müller
        • arc42 in Aktion (German) by Gernot Starke and Peter Hrschuka
        • Software Architecture for devlopers by Simon Brown
        • The C4 model for visualizing software architecture by Simon Brown
        • Docs Like Code by Anne Gentle

        DevOps Flow

        Mike's Notes

        Here are my working notes from day 4 of building the DevOps Engine for Pipi 9.

        Resources

        References

        • Reference

        Repository

        • Home > Ajabbi Research > Library >
        • Home > Handbook > 

        Last Updated

        17/05/2025

          DevOps Flow

          By: Mike Peters
          26/02/2025

          Mike is the inventor and architect of Pipi and the founder of Ajabbi.

          The start of the roadmap

          In 2024, I initially used a simple one-page Google Sheet as a roadmap to discuss the build with Alex and Chris. Then, a web page mockup with the same information was published on the Ajabbi developer website. The next step is to get a DevOps Engine to generate and use the roadmap to organise the work.

          Reinventing the wheel

          Unfortunately, Pipi 9 can't use existing DevOps tooling because of Pipi's novel internal architecture. Everything acts autonomously and self-organises, which affects testing. In fact, Pipi will have to build, test, and deploy itself while running live.

          Immediate objective - one version of the truth

          Create a simple web UI that interacts with a dedicated database to manage development, track versioning, and output a web page for the road map. The rest can come later.

          Data Model

          • The initial data model for the DevOps Engine (dvp) is now completed.
          • It prioritises flow.

          Constraints

          • Work in Progress (WIP) - needs to be small enough for fast flow
          • Batch Size - maybe 1
          • % Resource Busy - should be around 85%
          One idea I had was to allow users to let Pipi learn to adjust the WIP limit automatically to maximise flow.
          • 1
          • 2
          • 3
          • 4
          • 5
          • Automatic

          DevOps Engine

          • There can be many copies of the DevOps Engine. Each team will have its own or go with a multi-tenanted engine.
          • A DevOps Engine will be required to develop another DevOps Engine. (All engines are versioned)
          • Each DevOps Engine can be configured differently.
          • The DevOps Engine works directly on agents, not systems. Systems are emergent and configured using parameters, rules, weights, state history, boundaries, path taken, environment, Markov, Fuzzy, etc.

          Other Engines

          These have yet to be designed. They handle the specifics of each step or stage. The DevOps Engine will act as a wrapper around these other engines, which are not currently needed.

          • Plan
          • Code
          • Build
          • Test
          • Release
          • Deploy
          • Operate
          • Monitor
          Each of these different engines could interact with even more engines.
          • Render
          • Feature Flag
          • Update
          • etc

          DORA Metrics yet to be catered for

          • Deployment Frequency: Time between code deployments.
          • Mean Lead Time for Changes: Time between code commit and deployment.
          • Change Failure Rate: Percentage of deployments causing production issues.
          • Mean Time To Recovery: Time to resolve production issues.
          • Reliability (added in 2021): Measures operational performance, focusing on availability and adherence to user expectations.