InfoQ Homepage Documentation Content on InfoQ

Articles

RSS Feed

Newer Older

Development

The Renaissance of Code Documentation: Introducing Code Walkthrough

The Continuous Documentation methodology is a useful paradigm that helps ensure that high-quality documentation is created, maintained, and readily available. Code Walkthroughs take the reader on a “walk” — visiting at least two stations in the code — describe flows and interactions, and often incorporate code snippets.

Omer Rosenbaum Tom Ahi Dror
on Nov 10, 2021
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

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

Using OpenAPI to Build Smart APIs for Dumb Machines

This article discusses how to build, manage and maintain APIs with OpenAPI, including some of the most notable features in v. 3.0.

Adam Leventhal
on Jun 21, 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

How the TOGAF Standard Serves Enterprise Architecture

Any architect working with large enterprise systems has probably looked for guidance on how to manage the complexity and communicate with various stakeholders. This introductory overview of the TOGAF standard explains the structure of the framework, as well as discusses the benefits of using enterprise architecture to manage complex systems.

Will Stevens
on Sep 11, 2018
Development

Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs

API documentation is an often overlooked part of making any API a success. This article explores how to make the documentation part of a continuous integration pipeline keeping it closer to the code itself.

Anne Gentle
on Apr 25, 2017
Development

Virtual Panel: Document and Description Formats for Web APIs

In this virtual panel we hear from 4 individuals deeply involved in the Web API space. Each of them has a unique take on the values, benefits, and costs of documentation and description formats in general, and provide their own unique perspective from their vantage points across the Web. They agree on one thing: something must be done to help developers find their way through the world of Web APIs

Benjamin Young
on Oct 14, 2016
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
User Story Driven Docs

At OutSystems we stopped trying to document the UI and started doing user story driven documentation. In this article I'll tell you why you should avoid document the UI, and how to check if you're already doing it. I'll also tell you how focusing on user stories changed our team's culture, and the process we're currently using to create documentation for OutSystems Platform.

Joao Fernandes
on Jul 03, 2015
Profiles on the Web: An Interview with Erik Wilde

Erik Wilde talks to Mike Amundsen about Profiles, Description, Documentation, Discovery, his Sedola project and the future of Web-level metadata for APIs.

Mike Amundsen
on Jul 02, 2015
Lean Documentation

Knowledge about system and domain, which is important for both effectiveness and good quality, is best acquired through a dialog, face2face. Unfortunately, there are situations when a dialog is not possible and our only rescue is lean documentation. This article gives you 6 practices how to maximize information while minimizing the number of words. This makes it easy to use and to maintain.

Tomas Björkholm
on Apr 09, 2015