Facilitating the spread of knowledge and innovation in professional software development



Choose your language

InfoQ Homepage Documentation Content on InfoQ

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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.

  • 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

  • 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.

  • 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.

  • 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.

  • 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.

  • Conversation Patterns for Software Professionals. Part 3

    The third article of the Conversation Patterns for Software Professionals series is focused on very powerful tool which is a Conversation Structure. Michael explains the structure and the mechanics of what people call “a talk”, shows how to control the conversation flow and how to navigate through a conversation on purpose.