book

Living Documentation: Continuous Knowledge Sharing by Design, First Edition

Name: Living Documentation: Continuous Knowledge Sharing by Design, First Edition
Author: Cyrille Martraire
ISBN: 9780134689418

by Cyrille Martraire

May 2019

Intermediate to advanced

480 pages

13h 20m

English

Addison-Wesley Professional

Read now

Unlock full access

Cover Page
About This eBook
Halftitle Page
Title Page
Copyright Page
Dedication Page
Contents
Acknowledgments
About the Author
Introduction

Figure Credits
Chapter 1: Rethinking Documentation
A Tale from the Land of Living DocumentationWhy This Feature?Tomorrow You Won’t Need This Sketch AnymoreSorry, We Don’t Have Marketing Documents!You Keep Using This Word, but This Is Not What It MeansShow Me the Big Picture, and You’ll See What’s Wrong ThereThe Future of Living Documentation Is NowThe Problem with Traditional DocumentationDocumentation Is Not Cool, UsuallyThe Flaws of DocumentationThe Agile Manifesto and DocumentationIt’s Time for Documentation 2.0Documentation Is About KnowledgeThe Origination of KnowledgeHow Does Knowledge Evolve?Why Knowledge Is NecessaryDocumentation Is About Transferring KnowledgeFocusing on What MattersCore Principles of Living DocumentationReliableLow EffortCollaborativeInsightfulHow Ants Exchange Knowledge: StigmergyMost Knowledge Is Already ThereInternal DocumentationInternal Versus External DocumentationExamples of Internal and External DocumentationPreferring Internal DocumentationIn Situ DocumentationMachine-Readable DocumentationSpecific Versus Generic KnowledgeLearning Generic KnowledgeFocusing on Specific KnowledgeEnsuring Documentation AccuracyAccuracy Mechanism for Reliable DocumentationWhen Documentation Does Not Need an Accuracy MechanismBig Questions to Challenge Your DocumentationQuestioning the Need for Documentation at AllNeed for Documentation Because of Lack of TrustJust-in-Time Documentation, or a Cheap Option on Future KnowledgeQuestioning the Need for Traditional DocumentationMinimizing Extra Work NowMinimizing Extra Work LaterMaking an Activity FunDocumentation RebootLiving Documentation: The Very Short VersionApproaches to Better DocumentationA Gateway to DDDDomain-Driven Design in a NutshellLiving Documentation and Domain-Driven DesignWhen Living Documentation Is an Application of DDDA Story of Mutual Roots Between BDD, DDD, XP, and Living DocumentationSummary
Chapter 2: Behavior-Driven Development as an Example of Living Specifications
BDD Is All About ConversationsBDD with Automation Is All About Living DocumentationRedundancy and ReconciliationThe Anatomy of Scenarios in a FileThe Intent of a Feature FileFeature File ScenariosSpecification DetailsTags in Feature FilesScenarios as Interactive Living DocumentationScenarios in Boring Paper DocumentsA Feature File ExampleA Canonical Case of Living Documentation in Every AspectGoing Further: Getting the Best of Your Living DocumentationProperty-Based Testing and BDDSummary
Chapter 3: Knowledge Exploitation
Identifying Authoritative KnowledgeWhere Is the Knowledge Now?Single-Source PublishingSome Examples of Producing a Published DocumentA Published Snapshot with a Version NumberRemarksSetting Up a Reconciliation Mechanism (aka Verification Mechanism)Running Consistency TestsReconciliation on the Test AssumptionsPublished ContractsConsolidating Dispersed FactsHow Consolidation WorksConsolidation Implementation ConsiderationsReady-Made DocumentationThe Power of a Standard VocabularyLinking to Standard KnowledgeMore Than Just VocabularyUsing Ready-Made Knowledge in Conversation to Speed Up Knowledge TransferTools HistorySummary
Chapter 4: Knowledge Augmentation
When Programming Languages Are Not EnoughDocumentation Using AnnotationsAnnotations as More Than TagsDescribing the Rationale Behind DecisionsEmbedded LearningDocumentation by ConventionLiving Documentation in Legacy Code with ConventionsDocumenting the ConventionsConsistently Adhering to ConventionsThe Limitations of ConventionsExternal Documentation MethodsSidecar FilesMetadata DatabasesDesigning Custom AnnotationsStereotypical PropertiesStereotypes and Tactical PatternsUsing Meaningful Annotation Package NamesHijacking Standard AnnotationsStandard Annotation: @Aspect and Aspect-Oriented ProgrammingAnnotation by Default or Unless NecessaryHandling Module-Wide KnowledgeDealing with Many Kinds of ModulesModule-Wide Augmentation In PracticeIntrinsic Knowledge AugmentationMachine-Accessible DocumentationRecording Your RationaleWhat’s in a Rationale?Making the Rationale ExplicitBeyond Documentation: Motivated DesignAvoid Documenting SpeculationSkills as Pre-Documented RationalesRecording the Rationale as an Enabler for ChangeAcknowledging Your Influences (aka Project Bibliography)Declaring Your StyleCommit Messages as Comprehensive DocumentationCommit GuidelinesSummary
Chapter 5: Living Curation: Identifying Authoritative Knowledge
Dynamic CurationExamples of Dynamic CurationEditorial CurationLow-Maintenance Dynamic CurationOne Corpus of Knowledge for Multiple UsesScenario DigestsHighlighting the CoreHighlighting Inspiring ExemplarsGuided Tours and Sightseeing MapsCreating a Sightseeing MapCreating a Guided TourCreating a Living Guided TourA Poor Man’s Literate ProgrammingSumming Up: The Curator Preparing an Art ExhibitionSelecting and Organizing Existing KnowledgeAdding What’s Missing When NeededAccessibility for People Who Can’t Attend and for PosteritySummary
Chapter 6: Automating Documentation
Living DocumentsSteps in Creating a Living DocumentPresentation RulesLiving GlossariesHow a Living Glossary WorksAn Example Please!Information Curation for Living DocumentsCreating a Glossary Within a Bounded ContextCase Study of a Living GlossaryLiving DiagramsDiagrams Assist in ConversationsOne Diagram, One StoryLiving Diagrams to Keep You HonestThe Quest for the Perfect DiagramRendering a Living DiagramVisualization GuidelinesExample: Hexagonal Architecture Living DiagramCase Study: A Business Overview as a Living DiagramExample: A Context DiagramThe Challenges with Automated Generation of Design DocumentationSummary
Chapter 7: Runtime Documentation
Example: Living Services DiagramA Matter of Augmented Code but at RuntimeDiscovering the ArchitectureThe Magic That Makes This WorkGoing FurtherVisible Workings: Working Software as Its Own DocumentationVisible TestsDomain-Specific NotationGenerating Custom Domain-Specific Diagrams to Get Visual FeedbackExample: A Visible Test When Using Event SourcingA Concrete Example in CodeLiving Diagrams from Event Sourcing ScenariosIntrospectable Workings: Code in Memory as a Source of KnowledgeIntrospecting with ReflectionIntrospecting Without ReflectionSummary
Chapter 8: Refactorable Documentation
Code as DocumentationText LayoutCoding ConventionsNaming as the Primary DocumentationComposed Methods: You Need to Name ThemIdiomatic Naming Is ContextualCoding Against a FrameworkType-Driven DocumentationFrom Primitives to TypesDocumented Types and Integrated DocumentationTypes and AssociationsTypes over CommentsThe Composed MethodFluent StyleUsing an Internal DSLImplementing a Fluent InterfaceFluent TestsCreating a DSTLWhen Not to Use a Fluent StyleCase Study: An Example of Refactoring Code, Guided by CommentsIntegrated DocumentationType HierarchyCode SearchingSemantics Derived from Actual UsageUsing Plain-Text DiagramsExample: Plain-Text DiagramsDiagrams as CodeSummary
Chapter 9: Stable Documentation
Evergreen ContentRequirements Are More Stable Than Design DecisionsHigh-Level Goals Tend to Be StableA Lot of Knowledge Is Less Stable Than It LooksCase Study: A README FileTips for Evergreen DocumentationAvoiding Mixing Strategy Documentation with the Documentation of Its ImplementationEnsuring StabilityUsing Perennial NamingOrganizing Artifacts Along Stable AxesLinked KnowledgeVolatile-to-Stable DependenciesBroken Link CheckersLink RegistryBookmarked SearchesCategories of Stable KnowledgeEvergreen READMEVision StatementDomain Vision StatementsGoalsImpact MappingInvesting in Stable KnowledgeDomain ImmersionInvestigation WallDomain TrainingLive-My-Life SessionsShadow UsersA Long-Term InvestmentSummary
Chapter 10: Avoiding Traditional Documentation
Conversations About Formal DocumentationWiio’s LawsThe Rule of Three InterpretationsObstacles to ConversationsWorking Collectively for Continuous Knowledge SharingPair ProgrammingCross ProgrammingMob ProgrammingThe Three Amigos (or More)Event Storming as an Onboarding ProcessKnowledge Transfer SessionsContinuous DocumentationTruck FactorCoffee Machine CommunicationIdea SedimentationThrow-Away DocumentationOn-Demand DocumentationJust-in-Time DocumentationProvoking Just-in-Time Learning EarlyAstonishment ReportIncluding Some Upfront DocumentationInteractive DocumentationDeclarative AutomationDeclarative StyleDeclarative Dependency ManagementDeclarative Configuration ManagementDeclarative Automated DeploymentMachine DocumentationRemarks on Automation in GeneralEnforced GuidelinesSome Examples of RulesEvolving the GuidelinesEnforcement or EncouragementDeclarative GuidelinesA Matter of ToolsGuidelines or Design Documentation?Warranty Sticker Void if Tampered WithTrust-First CultureConstrained BehaviorMaking It Easy to Do the Right ThingMaking Mistakes Impossible: Error-Proof APIDesign Principles for Documentation AvoidanceReplaceability FirstConsistency FirstExample: The Zero Documentation GameContinuous TrainingSummary
Chapter 11: Beyond Documentation: Living Design
Listening to the DocumentationWhat Happened to the Language of the Domain?Programming by Coincidence DesignDeliberate Decision Making“Deliberate Decision” Does Not Mean “Upfront Decision”Documentation Is a Form of Code ReviewShameful DocumentationExample: Shameful DocumentationThe Troubleshooting GuideShameful Code DocumentationDocumenting Errors or Avoiding Errors?Documentation-Driven DevelopmentDocumentation to Keep You HonestThe Apparent Contradiction Between Documentation Driven and “Avoiding Documentation”Abusing Living Documentation (Anti-pattern)Procrastination by Living DocumentationBiodegradable DocumentationHygienic TransparencyDiagnostic ToolsPositive Pressure to Clean the InsideDesign Skills EverywhereReporter Porter Interviewing Mr. Living Doc DocSummary
Chapter 12: Living Architecture Documentation
Documenting the ProblemAn Example of a Problem BriefExplicit Quality AttributesStake-Driven Architecture DocumentationExplicit AssumptionsBrevity Suggests QualityEvolving Continuously: Change-Friendly DocumentationDecision LogsAn Example of a Structured Decision LogJournals or Blogs as Brain DumpsFractal Architecture DocumentationThe Architecture LandscapeArchitecture Diagrams and NotationsAn Architecture CodexTransparent ArchitectureArchitectural AnnotationsEnforced Design DecisionsArchitectural Reality CheckTest-Driven ArchitectureQuality Attributes as ScenariosQuality Attributes at Runtime in ProductionOther Quality AttributesFrom Fragmented Knowledge to Usable DocumentationSmall-Scale Simulation as Living Architecture DocumentationThe Desirable Properties of a Small-Scale SimulationTechniques to Simplify a SystemBuilding a Small-Scale Simulation Is Half the FunSystem MetaphorExplaining a System by Talking About Another SystemUseful Even Without Prior KnowledgeA Metaphor in Another MetaphorSummary
Chapter 13: Introducing Living Documentation to a New Environment
Undercover ExperimentsOfficial AmbitionNew Things Have to Work and Have to Be AcceptedStarting GentlyGoing Big and VisibleCase Study: A Tale of Introducing Living Documentation to a Team MemberConversations FirstThe First DebriefingTime to Talk About the CodeDecision Logs and Guided ToursCommon Objections to Living DocumentationAnnotations Are Not Meant for Documentation“We Do It Already”Migrating Legacy Documentation into Living DocumentationMarginal DocumentationCase Study: Introducing Living Documentation in a Batch SystemREADME and Ready-Made DocumentationBusiness BehaviorVisible Workings and a Single Source of TruthIntegrated Documentation for Developers and a Living Glossary for Other StakeholdersA Living Diagram to Show the Design IntentContact Information and Guided ToursMicroservices Big PictureSelling Living Documentation to ManagementStarting with an Actual ProblemA Living Documentation InitiativeContrasting the Current Situation with the Promise of a Better World to Match People’s AspirationsCompliance in SpiritCase Study: Compliance with ITILThe ITIL ExampleSummary
Chapter 14: Documenting Legacy Applications
Documentation BankruptcyLegacy Application as Fossilized KnowledgeArcheologyBubble ContextSuperimposed StructureHighlighted StructureExternal AnnotationsBiodegradable TransformationExample: Strangler ApplicationExample: BankruptcyAgree on MaximsEnforced Legacy RulesSummary
Chapter 15: Extra: Conspicuous Documentation
Focusing on DifferencesHow Is Your Lemon?Tell Only What’s UnknownSegmenting by Known AudienceFlexible ContentLow-Fidelity ContentVisual FacilitationSearch-Friendly DocumentationConcrete Examples, Together, NowIn PracticeFast Media and Prior PreparationTogether, NowStack Overflow DocumentationAffordable and AttractiveSpecs DigestEaster Eggs and Fun AnecdotesPromoting NewsUnorthodox MediaMaximsPosters and Domestic AdsMeme-Based PostersInformation RadiatorsHumor and Cheap MediaGoodies/SwagComicsInfodecksVisualizations and AnimationsLEGO BricksFurniture3D Printed StuffSummary
Index
Code Snippets

Content preview from Living Documentation: Continuous Knowledge Sharing by Design, First Edition

Introduction

I never planned to write a book on living documentation. I didn’t even have in mind that this topic was worth a book.

Long ago, I had a grandiose dream of creating tools that could understand the design decisions we make when coding. I spent a lot of free time over several years trying to come up with a framework for that, only to find out it’s very hard to make such a framework suitable for everyone. However, I tried the idea whenever it was helpful in the projects I was working on.

In 2013 I was speaking at Øredev on refactoring specifications. At the end of the talk I mentioned some of the ideas I’d been trying over time, and I was surprised at the enthusiastic feedback I received about the living documentation ideas. That is ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Design Patterns in the Real World, an Analysis-Based Approach

Publisher Resources

ISBN: 9780134689418

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Living Documentation: Continuous Knowledge Sharing by Design, First Edition

by Cyrille Martraire

Introduction

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.