InfoQ Homepage Architecture Documentation Content on InfoQ

Articles

RSS Feed

Newer Older

Architecture & Design

Has Your Architectural Decision Record Lost Its Purpose?

Architectural Decision Records (ADRs) are important vehicles for communicating the architectural decisions a development team makes about a system. Lacking a clear definition of what is architectural, and also lacking anywhere else to record important decisions, they can start to drift from their original purpose and lose focus and effectiveness.

Pierre Pureur Kurt Bittner
on Oct 25, 2023
DevOps

From Couch to Continuous Documentation: Incorporating Documentation into the Development Workflow

As software teams and projects grow, they suffer from knowledge management pains related to their code - lengthy onboarding, limiting knowledge silos, complex code, and risk of attrition. Creating Walkthrough Documentation while practicing Continuous Documentation can address most of the problems that relate to code-related knowledge sharing and management.

Tom Ahi Dror Eyal Ittah
on Mar 04, 2022
DevOps

Shifting to Continuous Documentation as a New Approach for Code Knowledge

Documentation is an important part of code development. However, documentation quickly becomes stale as code changes. Continuous documentation focuses on three principles: continuously verifying documents, documenting when it is most needed, and coupling the documentation to the code.

Omer Rosenbaum
on Jun 03, 2021
Architecture & Design

Information Relativity

To build great software, we need to account for perspective and relativity. Perspective is something's meaning depending on where it's observed from. Relativity refers to a distortion due to the location of the observer.

John Rauser
on Apr 12, 2021
Architecture & Design

Q&A with Cyrille Martraire on the Book Living Documentation

Cyrille Martraire argues that we should rethink how we work with documentation when building software systems — we should embrace documentation that evolves at the same pace as the code. In the book, he describes the concepts and ideas that are the base for living documentation and uses practical examples on how documentation that is always up-to-date can be created.

Jan Stenberg Cyrille Martraire
on Sep 22, 2019
Architecture & Design

Why Do We Need Architectural Diagrams?

Software architecture diagrams, when created well, and sparingly, can greatly improve communication within the development team and with external stakeholders. They require an understanding of the intended audience, and thoughtful restraint on what to include. Resist the temptation to think that diagrams are unnecessary or unhelpful, simply because there have been plenty of cases of bad diagrams.

Ionut Balosin
on Jan 19, 2019
Architecture & Design

The C4 Model for Software Architecture

Software architecture diagrams can be a very useful communication tool, but many teams have scaled back on the creation of diagrams, and when diagrams are created, they are often confusing and unclear. The C4 model consists of a hierarchical set of software architecture diagrams for context, containers, components, and code.

Simon Brown
on Jun 25, 2018
Architecture & Design

Guide to Digital Transformation - Part 2

This article introduces a new framework for translating a digital business ambition into imaginable digital strategies, that can be priced and modeled for impact analysis and economic value creation .

Philippe Assouline
on May 01, 2018
Architecture & Design

Guide to Digital Transformation. Define, Price, and Plan a Digital Transformation (Part 1)

Realizing the value of a great digital business vision traditionally required the arduous exercise of building the proper operational, technology, and human capabilities. This article introduces a framework for easily translating a digital business ambition into imaginable digital strategies, that can then be priced and architecturally modeled for impact analysis and economic value creation.

Philippe Assouline
on Apr 24, 2018
Architecture & Design

Driving Architectural Simplicity - The Value, Challenge, and Practice of Simple Solutions

Simple architectures are the most efficient and, subsequently, successful over their lifetime. Achieving simplicity is hard and requires continuous dedication. As an industry, we need to focus more on the system quality of architectural simplicity.

Brandon Bryson
on Aug 17, 2017
Architecture & Design

The Art of Crafting Architectural Diagrams

Architectural diagrams can be useful tools for documenting and communicating the design of a system. They must be self descriptive, consistent, accurate enough and connected to the code. Applying some guidelines can ensure the diagrams are useful to a variety of stakeholders.

Ionut Balosin
on Aug 04, 2017
Culture & Methods

Towards an Agile Software Architecture

Boyan Mihaylov covers his experience when working with both traditional waterfall software architectures and agile ones. He depicts the similarities and differences between these with a focus on three areas: the specifics of the software architect role, the timespan of the software architecture, and the output of the software architecture.

Boyan Mihaylov
on Dec 28, 2015