Home > Store

Living Documentation: Continuous Knowledge Sharing by Design

Register your product to gain access to bonus material or receive a coupon.

Living Documentation: Continuous Knowledge Sharing by Design

Best Value Purchase

Book + eBook Bundle

  • Your Price: $56.79
  • List Price: $97.98
  • Includes EPUB and PDF
  • About eBook Formats
  • This eBook includes the following formats, accessible from your Account page after purchase:

    ePub EPUB The open industry format known for its reflowable content and usability on supported mobile devices.

    Adobe Reader PDF The popular standard, used most often with the free Acrobat® Reader® software.

    This eBook requires no passwords or activation to read. We customize your eBook by discreetly watermarking it with your name, making it uniquely yours.

More Purchase Options

Book

  • Your Price: $39.99
  • List Price: $49.99
  • Usually ships in 24 hours.

eBook (Watermarked)

  • Your Price: $38.39
  • List Price: $47.99
  • Includes EPUB and PDF
  • About eBook Formats
  • This eBook includes the following formats, accessible from your Account page after purchase:

    ePub EPUB The open industry format known for its reflowable content and usability on supported mobile devices.

    Adobe Reader PDF The popular standard, used most often with the free Acrobat® Reader® software.

    This eBook requires no passwords or activation to read. We customize your eBook by discreetly watermarking it with your name, making it uniquely yours.

About

Features

  • Illuminates powerful opportunities to drive business value through better, more relevant and timely documentation
  • Transforms writing documentation from a mundane task to one that’s as much fun as coding
  • Helps students improve their software with better roadmaps and context, and greater clarity

Description

  • Copyright 2019
  • Dimensions: 7" x 9-1/8"
  • Pages: 480
  • Edition: 1st
  • Book
  • ISBN-10: 0-13-468932-1
  • ISBN-13: 978-0-13-468932-6

Software documentation: a necessary evil? It needn’t be! Documentation can come to life, evolve, stay dynamic, and actually help you build better software.

This concise guide introduces and thoroughly illuminates the concept of living documentation that changes at the same pace as software design and development, from establishment of business goals to capturing domain knowledge, creating architecture, designing software, coding, and deployment. Replete with clarifying illustrations and concrete examples, it shows how to dramatically improve your documentation at minimal extra cost by using well-crafted artifacts and judicious automation.

Language- and technology-agnostic. Living Documentation borrows powerful ideas from domain-driven design, helping you customize its concepts and apply its lessons to meet your changing documentation needs in your own specific domain. Cyrille Martraire proves that you don’t have to choose between working software and comprehensive, high-quality documentation: you can have the benefits of both.

Downloads

Downloads

Download: Pattern Diagrams (927 KB .pdf)

Sample Content

Online Sample Chapter

Software Documentation: Identifying Authoritative Knowledge

Table of Contents

Introduction

Chapter 1: Rethinking Documentation

A Tale from the Land of Living Documentation

    Why This Feature?

    Tomorrow You Won’t Need This Sketch Anymore

    Sorry, We Don’t Have Marketing Documents!

    You Keep Using This Word, but This Is Not What It Means

    Show Me the Big Picture, and You’ll See What’s Wrong There

    The Future of Living Documentation Is Now

The Problem with Traditional Documentation

    Documentation Is Not Cool, Usually

    The Flaws of Documentation

    The Agile Manifesto and Documentation

    It’s Time for Documentation 2.0

Documentation Is About Knowledge

    The Origination of Knowledge

    How Does Knowledge Evolve?

    Why Knowledge Is Necessary

Documentation Is About Transferring Knowledge

    Focusing on What Matters

Core Principles of Living Documentation

    Reliable

    Low Effort

    Collaborative

    Insightful

    How Ants Exchange Knowledge: Stigmergy

Most Knowledge Is Already There

Internal Documentation

    Internal Versus External Documentation

    Examples of Internal and External Documentation

    Preferring Internal Documentation

    In Situ Documentation

    Machine-Readable Documentation

Specific Versus Generic Knowledge

    Learning Generic Knowledge

    Focusing on Specific Knowledge

Ensuring Documentation Accuracy

    Accuracy Mechanism for Reliable Documentation

    When Documentation Does Not Need an Accuracy Mechanism

Big Questions to Challenge Your Documentation

    Questioning the Need for Documentation at All

    Need for Documentation Because of Lack of Trust

    Just-in-Time Documentation, or a Cheap Option on Future Knowledge

    Questioning the Need for Traditional Documentation

    Minimizing Extra Work Now

    Minimizing Extra Work Later

Making an Activity Fun

Documentation Reboot

    Living Documentation: The Very Short Version

    Approaches to Better Documentation

A Gateway to DDD

    Domain-Driven Design in a Nutshell

    Living Documentation and Domain-Driven Design

    When Living Documentation Is an Application of DDD

    A Story of Mutual Roots Between BDD, DDD, XP, and Living Documentation

Summary

Chapter 2: Behavior-Driven Development as an Example of Living Specifications

BDD Is All About Conversations

BDD with Automation Is All About Living Documentation

    Redundancy and Reconciliation

The Anatomy of Scenarios in a File

    The Intent of a Feature File

    Feature File Scenarios

    Specification Details

    Tags in Feature Files

    Scenarios as Interactive Living Documentation

    Scenarios in Boring Paper Documents

A Feature File Example

A Canonical Case of Living Documentation in Every Aspect

Going Further: Getting the Best of Your Living Documentation

    Property-Based Testing and BDD

Summary

Chapter 3: Knowledge Exploitation

Identifying Authoritative Knowledge

Where Is the Knowledge Now?

Single-Source Publishing

    Some Examples of Producing a Published Document

    A Published Snapshot with a Version Number

    Remarks

Setting Up a Reconciliation Mechanism (aka Verification Mechanism)

    Running Consistency Tests

    Reconciliation on the Test Assumptions

    Published Contracts

Consolidating Dispersed Facts

    How Consolidation Works

    Consolidation Implementation Considerations

Ready-Made Documentation

    The Power of a Standard Vocabulary

    Linking to Standard Knowledge

    More Than Just Vocabulary

    Using Ready-Made Knowledge in Conversation to Speed Up Knowledge Transfer

Tools History

Summary

Chapter 4: Knowledge Augmentation

When Programming Languages Are Not Enough

Documentation Using Annotations

    Annotations as More Than Tags

    Describing the Rationale Behind Decisions

    Embedded Learning

Documentation by Convention

    Living Documentation in Legacy Code with Conventions

    Documenting the Conventions

    Consistently Adhering to Conventions

    The Limitations of Conventions

External Documentation Methods

    Sidecar Files

    Metadata Databases

Designing Custom Annotations

    Stereotypical Properties

    Stereotypes and Tactical Patterns

    Using Meaningful Annotation Package Names

    Hijacking Standard Annotations

    Standard Annotation: @Aspect and Aspect-Oriented Programming

    Annotation by Default or Unless Necessary

Handling Module-Wide Knowledge

    Dealing with Many Kinds of Modules

    Module-Wide Augmentation In Practice

Intrinsic Knowledge Augmentation

Machine-Accessible Documentation

Recording Your Rationale

    What’s in a Rationale?

    Making the Rationale Explicit

    Beyond Documentation: Motivated Design

    Avoid Documenting Speculation

    Skills as Pre-Documented Rationales

    Recording the Rationale as an Enabler for Change

Acknowledging Your Influences (aka Project Bibliography)

    Declaring Your Style

Commit Messages as Comprehensive Documentation

    Commit Guidelines

Summary

Chapter 5: Living Curation: Identifying Authoritative Knowledge

Dynamic Curation

    Examples of Dynamic Curation

    Editorial Curation

    Low-Maintenance Dynamic Curation

    One Corpus of Knowledge for Multiple Uses

    Scenario Digests

Highlighting the Core

Highlighting Inspiring Exemplars

Guided Tours and Sightseeing Maps

    Creating a Sightseeing Map

    Creating a Guided Tour

    Creating a Living Guided Tour

    A Poor Man’s Literate Programming

Summing Up: The Curator Preparing an Art Exhibition

    Selecting and Organizing Existing Knowledge

    Adding What’s Missing When Needed

    Accessibility for People Who Can’t Attend and for Posterity

Summary

Chapter 6: Automating Documentation

Living Documents

    Steps in Creating a Living Document

    Presentation Rules

Living Glossaries

    How a Living Glossary Works

    An Example Please!

    Information Curation for Living Documents

    Creating a Glossary Within a Bounded Context

    Case Study of a Living Glossary

Living Diagrams

    Diagrams Assist in Conversations

    One Diagram, One Story

    Living Diagrams to Keep You Honest

    The Quest for the Perfect Diagram

    Rendering a Living Diagram

    Visualization Guidelines

    Example: Hexagonal Architecture Living Diagram

    Case Study: A Business Overview as a Living Diagram

    Example: A Context Diagram

    The Challenges with Automated Generation of Design Documentation

Summary

Chapter 7: Runtime Documentation

Example: Living Services Diagram

    A Matter of Augmented Code but at Runtime

    Discovering the Architecture

    The Magic That Makes This Work

    Going Further

    Visible Workings: Working Software as Its Own Documentation

Visible Tests

    Domain-Specific Notation

    Generating Custom Domain-Specific Diagrams to Get Visual Feedback

Example: A Visible Test When Using Event Sourcing

    A Concrete Example in Code

    Living Diagrams from Event Sourcing Scenarios

Introspectable Workings: Code in Memory as a Source of Knowledge

    Introspecting with Reflection

    Introspecting Without Reflection

Summary

Chapter 8: Refactorable Documentation

Code as Documentation

    Text Layout

    Coding Conventions

Naming as the Primary Documentation

    Composed Methods: You Need to Name Them

    Idiomatic Naming Is Contextual

    Coding Against a Framework

Type-Driven Documentation

    From Primitives to Types

    Documented Types and Integrated Documentation

    Types and Associations

    Types over Comments

The Composed Method

Fluent Style

    Using an Internal DSL

    Implementing a Fluent Interface

    Fluent Tests

    Creating a DSTL

    When Not to Use a Fluent Style

Case Study: An Example of Refactoring Code, Guided by Comments

Integrated Documentation

    Type Hierarchy

    Code Searching

    Semantics Derived from Actual Usage

Using Plain-Text Diagrams

    Example: Plain-Text Diagrams

    Diagrams as Code

Summary

Chapter 9: Stable Documentation

Evergreen Content

    Requirements Are More Stable Than Design Decisions

    High-Level Goals Tend to Be Stable

    A Lot of Knowledge Is Less Stable Than It Looks

    Case Study: A README File

Tips for Evergreen Documentation

    Avoiding Mixing Strategy Documentation with the Documentation of Its Implementation

    Ensuring Stability

    Using Perennial Naming

    Organizing Artifacts Along Stable Axes

Linked Knowledge

    Volatile-to-Stable Dependencies

    Broken Link Checkers

    Link Registry

    Bookmarked Searches

Categories of Stable Knowledge

    Evergreen README

Vision Statement

    Domain Vision Statements

    Goals

    Impact Mapping

Investing in Stable Knowledge

    Domain Immersion

    Investigation Wall

    Domain Training

    Live-My-Life Sessions

    Shadow Users

    A Long-Term Investment

Summary

Chapter 10: Avoiding Traditional Documentation

Conversations About Formal Documentation

    Wiio’s Laws

    The Rule of Three Interpretations

    Obstacles to Conversations

Working Collectively for Continuous Knowledge Sharing

    Pair Programming

    Cross Programming

    Mob Programming

    The Three Amigos (or More)

    Event Storming as an Onboarding Process

    Knowledge Transfer Sessions

    Continuous Documentation

    Truck Factor

Coffee Machine Communication

Idea Sedimentation

Throw-Away Documentation

On-Demand Documentation

    Just-in-Time Documentation

    Provoking Just-in-Time Learning Early

    Astonishment Report

    Including Some Upfront Documentation

Interactive Documentation

Declarative Automation

    Declarative Style

    Declarative Dependency Management

    Declarative Configuration Management

    Declarative Automated Deployment

    Machine Documentation

    Remarks on Automation in General

Enforced Guidelines

    Some Examples of Rules

    Evolving the Guidelines

    Enforcement or Encouragement

    Declarative Guidelines

    A Matter of Tools

    Guidelines or Design Documentation?

    Warranty Sticker Void if Tampered With

    Trust-First Culture

Constrained Behavior

    Making It Easy to Do the Right Thing

    Making Mistakes Impossible: Error-Proof API

Design Principles for Documentation Avoidance

    Replaceability First

    Consistency First

Example: The Zero Documentation Game

    Continuous Training

Summary

Chapter 11: Beyond Documentation: Living Design

Listening to the Documentation

    What Happened to the Language of the Domain?

    Programming by Coincidence Design

Deliberate Decision Making

     “Deliberate Decision” Does Not Mean “Upfront Decision”

    Documentation Is a Form of Code Review

Shameful Documentation

    Example: Shameful Documentation

    The Troubleshooting Guide

    Shameful Code Documentation

    Documenting Errors or Avoiding Errors?

Documentation-Driven Development

    Documentation to Keep You Honest

    The Apparent Contradiction Between Documentation Driven and “Avoiding Documentation”

Abusing Living Documentation (Anti-pattern)

Procrastination by Living Documentation

Biodegradable Documentation

Hygienic Transparency

    Diagnostic Tools

    Positive Pressure to Clean the Inside

Design Skills Everywhere

Reporter Porter Interviewing Mr. Living Doc Doc

Summary

Chapter 12: Living Architecture Documentation

Documenting the Problem

    An Example of a Problem Brief

Explicit Quality Attributes

    Stake-Driven Architecture Documentation

    Explicit Assumptions

    Brevity Suggests Quality

    Evolving Continuously: Change-Friendly Documentation

Decision Logs

    An Example of a Structured Decision Log

    Journals or Blogs as Brain Dumps

Fractal Architecture Documentation

The Architecture Landscape

    Architecture Diagrams and Notations

An Architecture Codex

Transparent Architecture

    Architectural Annotations

    Enforced Design Decisions

Architectural Reality Check

Test-Driven Architecture

    Quality Attributes as Scenarios

    Quality Attributes at Runtime in Production

    Other Quality Attributes

    From Fragmented Knowledge to Usable Documentation

Small-Scale Simulation as Living Architecture Documentation

    The Desirable Properties of a Small-Scale Simulation

    Techniques to Simplify a System

    Building a Small-Scale Simulation Is Half the Fun

System Metaphor

    Explaining a System by Talking About Another System

    Useful Even Without Prior Knowledge

    A Metaphor in Another Metaphor

Summary

Chapter 13: Introducing Living Documentation to a New Environment

Undercover Experiments

    Official Ambition

New Things Have to Work and Have to Be Accepted

    Starting Gently

    Going Big and Visible

Case Study: A Tale of Introducing Living Documentation to a Team Member

    Conversations First

    The First Debriefing

    Time to Talk About the Code

    Decision Logs and Guided Tours

Common Objections to Living Documentation

    Annotations Are Not Meant for Documentation

     “We Do It Already”

Migrating Legacy Documentation into Living Documentation

Marginal Documentation

Case Study: Introducing Living Documentation in a Batch System

    README and Ready-Made Documentation

    Business Behavior

    Visible Workings and a Single Source of Truth

    Integrated Documentation for Developers and a Living Glossary for Other Stakeholders

    A Living Diagram to Show the Design Intent

    Contact Information and Guided Tours

    Microservices Big Picture

Selling Living Documentation to Management

    Starting with an Actual Problem

    A Living Documentation Initiative

    Contrasting the Current Situation with the Promise of a Better World to Match People’s Aspirations

Compliance in Spirit

    Case Study: Compliance with ITIL

    The ITIL Example

Summary

Chapter 14: Documenting Legacy Applications

Documentation Bankruptcy

Legacy Application as Fossilized Knowledge

    Archeology

Bubble Context

Superimposed Structure

Highlighted Structure

External Annotations

Biodegradable Transformation

    Example: Strangler Application

    Example: Bankruptcy

Agree on Maxims

Enforced Legacy Rules

Summary

Chapter 15: Extra: Conspicuous Documentation

Focusing on Differences

    How Is Your Lemon?

Tell Only What’s Unknown

    Segmenting by Known Audience

    Flexible Content

    Low-Fidelity Content

    Visual Facilitation

Search-Friendly Documentation

Concrete Examples, Together, Now

    In Practice

    Fast Media and Prior Preparation

    Together, Now

Stack Overflow Documentation

Affordable and Attractive

    Specs Digest

    Easter Eggs and Fun Anecdotes

    Promoting News

Unorthodox Media

    Maxims

    Posters and Domestic Ads

    Meme-Based Posters

    Information Radiators

    Humor and Cheap Media

    Goodies/Swag

    Comics

    Infodecks

    Visualizations and Animations

    LEGO Bricks

    Furniture

    3D Printed Stuff

Summary

9780134689326    TOC    4/17/2019 

Updates

Submit Errata

More Information

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020