├── README.md └── manuscript ├── BeyondDocumentation ├── AbusingLivingDocumentation.txt ├── BiodegradableDoc.txt ├── DeliberateDesign.jpg ├── DocumentationDrivenDevelopment.txt ├── ExpectedVsActual.jpg ├── HygienicTransparency.txt ├── ListenToTheDocumentation.txt ├── LivingDocumentationGoingWild.txt ├── Section------BeyondDocumentation.txt └── images │ ├── biodegradabledoc.png │ ├── curator.png │ ├── explore-capture-present.png │ ├── fool.png │ ├── listen_to_doc.png │ ├── over-complicated.png │ ├── visible_hygiene.png │ ├── wordcloud_bad.png │ └── wordcloud_good.png ├── Biblio.txt ├── Closing.txt ├── EfficientDocumentation ├── 3AmigosConversations.jpg ├── AffordableAttractive.txt ├── EfficientDocumentation.txt ├── EvenStupidDecisionsHadARationale.jpg ├── MicroservicesAsWalledCitiesMetaphor.jpg ├── SearchFriendly.txt ├── Section------EfficientDocumentation.txt ├── SpecificationWorkshops.txt ├── StackOverflowDocumentation.txt ├── UnorthodoxMedia.txt ├── _linear_navigation_path.txt └── images │ ├── areyouawesome.jpg │ ├── gofastgowell.jpg │ ├── likecounter.jpg │ ├── noprojects_poster.jpg │ └── tshirt.jpg ├── Frontmatter ├── HowToReadThisBook.txt ├── IntroductoryQuestions.txt ├── NoteToreviewers.txt ├── about.txt ├── credit.txt └── preface.txt ├── IntroducingLivingDocumentation ├── DocumentationCompliance.txt ├── DocumentationInLegacy.txt ├── IntroducingLivingDocumentation.txt ├── IntroducingLivingDocumentationByExample.txt ├── ProjectVsSystem.txt ├── Section------IntroducingLivingDocumentation.txt ├── SellingLivingDocumentation.txt └── images │ ├── SkillsMatrix.jpeg │ ├── legacy_annotation_registry.jpg │ ├── legacy_bad_modules.jpg │ ├── legacy_bubble_context.jpg │ ├── legacy_expected_vs_actual.jpg │ ├── legacy_expected_vs_actual.png │ ├── legacy_modules_mapping.jpg │ └── legacy_strangled_app.jpg ├── Introduction ├── AllAboutKnowledge.txt ├── Checklist.txt ├── DocumentationReboot.txt ├── Fun.txt ├── GatewayToDDD.txt ├── ImagineTheIdealStory.txt ├── KnowledgeIsAlreadyThere.txt ├── KnowledgeOrigination.txt ├── KnowledgeTransfer.txt ├── NecessaryKnowledge.txt ├── PeterNaurTheoryPassing.txt ├── Problem.txt ├── Section------Introduction.txt ├── SpecificVsGeneric.txt ├── _LD_DDD_mapping.txt └── images │ ├── 4-principles.png │ ├── 4_principles.jpg │ ├── brain_dump.png │ ├── chore_automation.png │ ├── copist.png │ ├── living_documentation_map.png │ ├── misleading_label.png │ ├── out_of_sync.png │ ├── procrastination.png │ ├── rate_of_change.png │ ├── separate_activities-old.jpg │ ├── separate_activities.jpg │ └── timesink.png ├── Introduction_Overview ├── AccuracyMechanism.txt ├── ExternalInternalDocumentation.txt ├── SpineModel.txt ├── _checklist_diagram.txt └── images │ └── color-coded-pompidou.png ├── KnowledgeAugmentation ├── AugmentedCode.txt ├── CommitMessages.txt ├── Curation.txt ├── CustomAnnotations.txt ├── DocumentationByAnnotations.txt ├── DocumentationByConvention.txt ├── HighlightedCore.txt ├── InspiringExamplars.txt ├── IntrinsicKnowledgeAugmentation.jpg ├── IntrinsicKnowledgeAugmentation.txt ├── LiterateProgramming.txt ├── MachineAccessibleDocumentation.txt ├── ModuleWideKnowledge.txt ├── RecordTheRationale.txt ├── SideCarFile_MetadataDB.txt ├── SightseeingMap.txt ├── _DocumentationByDSL.txt ├── _DocumentationRegistry.txt ├── _ExtendTheLiterature.txt └── images │ ├── annotation_tooltip.png │ ├── augmented_code.png │ ├── exemplar.png │ ├── fool.png │ ├── github_blame_view.png │ ├── highlighted_core_eclipse_search.png │ ├── what_were_they_thinking.png │ └── without_why_same_mistake_again.png ├── KnowledgeExploitation ├── InformationConsolidation.txt ├── KnowledgeExploitation.txt ├── OneArtifactMultipleUses.jpg ├── OneManuscriptMultipleDerivatives.jpg ├── ReadyMadeKnowledge.txt ├── ReadyMadeKnowledgeInConversation.txt ├── ReadyMadeKnowledge_patterns_criticism.txt ├── Reconciliation.txt ├── Section------KnowledgeExploitationAugmentation.txt ├── SingleSourcing.txt ├── ToolsHistory.txt ├── _HumaneRegistry.txt └── images │ ├── ConsolidatedView.jpg │ ├── JB1.png │ ├── JB2.png │ ├── JB3.png │ ├── JB4.png │ ├── Reconciliation.jpg │ ├── Reconciliation.png │ ├── consolidation_mechanism.jpg │ ├── element_of_a_system.png │ ├── reconciliation_mechanism.jpg │ ├── single_source_multiple_outputs.png │ └── single_sourcing_mechanism.jpg ├── LivingDesignArchitecture ├── ArchitectureLandscape.txt ├── LivingDesign.txt ├── Section------LivingDesignArchitecture.txt ├── SmallScaleSimulation.txt ├── SystemMetaphor.txt ├── TestDrivenArchitecture.txt ├── _service_registry.txt └── images │ ├── ReadyForExtension.jpg │ ├── codex.png │ ├── fool.png │ ├── james_lewis_cloud_diagram.png │ ├── megaphone.png │ ├── sales_funnel.png │ ├── transparent_architecture.png │ └── why_so_complicated.png ├── LivingDocumentation ├── BusinessDomainDiagram.txt ├── ContextDiagram.txt ├── DomainSpecificDiagrams.txt ├── HexagonalArchitectureDiagram.txt ├── LivingDiagram.txt ├── LivingDocument.txt ├── LivingGlossary.txt ├── LivingServicesDiagram.txt ├── PatternOrientedLivingDiagram.txt ├── Section------LivingDocumentation.txt ├── _LivingContextMap.txt ├── _LivingDiagramExamplesList.txt ├── _LivingGlossaryCaseStudy.txt └── images │ ├── alistair_hexagonal.gif │ ├── bc1.png │ ├── bc2.png │ ├── cash_timeline.png │ ├── domain-specific-svg1.png │ ├── domain-specific-svg2.png │ ├── element_of_a_system.png │ ├── enum.png │ ├── fool.png │ ├── hexagonal-sketch.jpg │ ├── hexagonal.jpg │ ├── hexagonal_living-diagram.png │ ├── hexagonal_living-diagram.tif │ ├── living-diagram1.jpg │ ├── living-diagram2.jpg │ ├── living_diagram_overview.png │ ├── musictheory_treeview.png │ ├── one-diagram-one-story.png │ ├── orderbook_table.jpg │ ├── overview.jpg │ ├── package-annotations.png │ ├── packages.png │ ├── pasted-image-6633.png │ ├── policy_timeline.png │ ├── rendered1.png │ ├── rendered2.png │ ├── rendered2bis.png │ ├── rendered3.png │ ├── rendered4.png │ ├── rendered_later.png │ ├── supply-chain-geo.jpg │ ├── supply-chain-timeline.jpg │ ├── supplychain.png │ ├── system_diagram_flottio.png │ ├── system_diagram_flottio2.png │ ├── useless-uml-diagram.png │ ├── vo.png │ └── zipkin_deps_tracegen.png ├── NoDocumentation ├── CoffeeMachineCommunication.txt ├── ConsistencyReplaceability.txt ├── ContinuousTraining.txt ├── Conversations.txt ├── DeclarativeAutomation.txt ├── EnforcedGuidelines.txt ├── IdeasSedimentation.txt ├── MakeItEasytoDotheRightThing.txt ├── MakingMistakesImpossible.txt ├── NoDocumentation.txt ├── NotDeclarativeAutomation.jpg ├── On-DemandDocumentation.txt ├── ReadyMadeKnowledge.jpg ├── Section------NoDocumentation.txt ├── ShamefulDocumentation.txt ├── WorkingCollectively.txt ├── ZeroDocumentation.txt └── images │ ├── ConversationsTraces.jpg │ ├── EnforcedArchitecture.png │ ├── decantation.png │ ├── diagram_communication_modes_alistair_cockburn.gif │ ├── diagram_communication_modes_alistair_cockburn.png │ ├── eclipse_pom_navigation.png │ ├── fool.png │ ├── foyer.jpg │ ├── header-menu.png │ ├── nodocumentation.jpg │ ├── puppet-graph-complex.png │ ├── sedimentation.jpg │ ├── sonar_rules.jpg │ ├── sonarreference.png │ └── visible_hygiene.png ├── README.txt ├── RefactorableDocumentation ├── CodeAsDocumentation.txt ├── ComposedMethod.txt ├── EventSourcingTests.txt ├── FluentStyle.txt ├── IntegratedDocumentation.txt ├── ModularDesign.jpg ├── NamingAsPrimaryDocumentation.txt ├── PlainTextArtifacts.txt ├── PlainTextDiagram.txt ├── PlainTextWithTags.jpg ├── RefactoringGuidedByComments.txt ├── Section------RefactorableDocumentation.txt ├── SourceControlReference.txt ├── TypeDrivenDocumentation.txt └── images │ ├── arrange_act_assert.png │ ├── command-event-diagram.png │ ├── composed_method_by_abstraction.png │ ├── diagrammr1.png │ ├── diagrammr2.png │ ├── dotdiagram_rendering.png │ ├── matching_expressions.png │ ├── napkin_sketch.png │ ├── table_code_layout.png │ ├── type_signature_search.png │ ├── type_signature_search_int.png │ └── uml_class_notation.png ├── Sample.txt ├── StableDocumentation ├── AcknowledgedInfluences.txt ├── DomainImmersion.txt ├── EvergreenDocument.txt ├── LinkRegistry.txt ├── PerennialNaming.txt ├── Section------StableDocumentation.txt ├── StrategyImplementationSeparation.txt ├── VisionStatement.txt └── images │ ├── fool.png │ └── napkin_sketch.png ├── Summary_TheCurator.txt ├── Summing_it_up_Interview_Doctor_by_Reporter.txt ├── VisibleWorkings ├── Interpreter.txt ├── IntrospectableWorkings.txt ├── Section------RuntimeDocumentation.txt ├── VisibleCalculation.txt ├── VisibleWorkings.txt └── images │ ├── introspectable-generated.png │ ├── introspectable.png │ └── introspecting.png ├── _AlternativeTitles.txt ├── _TheProcessOfWritingThisBook.txt ├── _attic ├── CollaborativeArtifactAsCode.txt ├── TraceableValues.txt ├── _CaseStudy_DesigningTags.txt ├── _CaseStudy_PetShop100%Patterns_BOF.txt ├── _CodeReadingAndProjectDiscovery.txt ├── _ComplianceDocWorkaround.txt ├── _DesignAnnotations.txt ├── _DesignDocumentation.txt ├── _DocumentationByAnnotations.txt ├── _DocumentationLandscape.txt ├── _DocumentationMigration_BRIEF.txt ├── _DocumentationStrategy.txt ├── _ITIL.txt ├── _ImplementationPrinciples.txt ├── _InterviewHeuristics.txt ├── _LayeredDotNet.txt ├── _LiterateProgramming.txt ├── _Minimum_Readme.txt ├── _More_TypeDrivenDocumentation.txt ├── _Patternity_PatternAnnotations.txt ├── _QueryableObjectLog.txt ├── _SkillsMatrix.txt ├── _SpecificNotations.txt ├── _TransparentConfiguration.txt ├── _blogs_etc.txt ├── _ideas.txt ├── _intrinsic_modules_declarations.txt ├── _legacy_doc_ideas.txt ├── _listen_to_doc.txt ├── _notes.txt ├── _quotesPeterHilton.txt ├── _quotes_C4_diagrams.txt ├── _quotes_DocumentingSwArch.txt ├── _quotes_PragProg.txt ├── _quotes_SamNewman_microservices.txt ├── _realworld_case_Bank1.txt └── _theoryBuilding.txt ├── _content_overview.txt ├── _encoding_characters_to_escape.txt ├── _imported ├── _domain_knowledge.txt ├── _humor_TODO.txt ├── _iosjournal1.txt ├── _iosjournal1bis.txt ├── _iosjournal2.txt ├── _journal3.txt ├── _notes.txt ├── _quote_twitter_convo_code_tells_WHAT_HOW_NOT_WHY.txt ├── _quotes_DocumentingArchofOpenSource.txt ├── _tools.txt ├── capture_ideas.png ├── explore_ideas.png ├── highlighted_core_eclipse_search.png ├── iosjournal2bis.txt ├── phases-1-2.png ├── phases-3-4.png ├── present_ideas.png ├── sales_funnel.png └── system_diagram_flottio.png ├── backmatter.txt ├── bdd ├── BDD.txt ├── RichDomainDescription.txt ├── Section------LivingDocumentationBDDExample.txt ├── _DocumentingBusinessBehavior.txt ├── _PropertyBasedTesting.txt ├── _more_BDD_examples.txt ├── _quotesFromSBE_GojkoAdzic.txt └── images │ ├── 3amigos.png │ ├── bdd-reconciliation.jpg │ ├── bdd-redundancy.jpg │ └── bdd-website.jpg ├── book.txt ├── courtesy_TODO.txt ├── frontmatter.txt ├── images ├── 3amigos.png ├── 4-principles.png ├── 4_principles.jpg ├── ConsolidatedView.jpg ├── ConversationsTraces.jpg ├── DocumentationDefinition.jpg ├── EnforcedArchitecture.jpg ├── EnforcedArchitecture.png ├── JB1.png ├── JB2.png ├── JB3.png ├── JB4.png ├── LD_map.png ├── ReadyForExtension.jpg ├── Reconciliation.jpg ├── Reconciliation.png ├── alistair_hexagonal.gif ├── alistair_hexagonal.png ├── annotation_tooltip.png ├── areyouawesome.jpg ├── arrange_act_assert.png ├── augmented_code.png ├── bc1.png ├── bc2.png ├── bdd-reconciliation.jpg ├── bdd-redundancy.jpg ├── bdd-website.jpg ├── biodegradabledoc.png ├── brain_dump.png ├── cash_timeline.png ├── chore_automation.png ├── codex.png ├── color-coded-pompidou.png ├── command-event-diagram.png ├── composed_method_by_abstraction.png ├── consolidation_mechanism.jpg ├── copist.png ├── curator.png ├── decantation.png ├── diagram_communication_modes_alistair_cockburn.gif ├── diagram_communication_modes_alistair_cockburn.png ├── diagrammr1.png ├── diagrammr2.png ├── domain-specific-svg1.png ├── domain-specific-svg2.png ├── dotdiagram_rendering.png ├── eclipse_pom_navigation.png ├── element_of_a_system.png ├── enum.png ├── exemplar.png ├── explore-capture-present.png ├── fool.png ├── foyer.jpg ├── github_blame_view.png ├── goals │ └── impact_map_micro_royalties.png ├── gofastgowell.jpg ├── header-menu.png ├── hexagonal-sketch.jpg ├── hexagonal.jpg ├── hexagonal_living-diagram.png ├── hexagonal_living-diagram.tif ├── highlighted_core_eclipse_search.png ├── introspectable-generated.png ├── introspectable.png ├── introspecting.png ├── james_lewis_cloud_diagram.png ├── legacy_annotation_registry.jpg ├── legacy_bad_modules.jpg ├── legacy_bubble_context.jpg ├── legacy_expected_vs_actual.jpg ├── legacy_expected_vs_actual.png ├── legacy_modules_mapping.jpg ├── legacy_strangled_app.jpg ├── likecounter.jpg ├── listen_to_doc.png ├── living-diagram-1-story.png ├── living-diagram1.jpg ├── living-diagram2.jpg ├── living_diagram_overview.png ├── living_documentation_map.jpg ├── living_documentation_map.png ├── living_glossary_overview.015.jpg ├── living_glossary_overview.016.jpg ├── livingdoc_doc.png ├── matching_expressions.png ├── megaphone.png ├── misleading_label.png ├── musictheory_treeview.png ├── napkin_sketch.png ├── nodocumentation.jpg ├── noprojects_poster.jpg ├── one-diagram-one-story.png ├── orderbook_table.jpg ├── originals │ ├── alistair_hexagonal.gif │ └── diagram_communication_modes_alistair_cockburn.gif ├── out_of_sync.png ├── over-complicated.png ├── overview.jpg ├── package-annotations.png ├── packages.png ├── pasted-image-6633.png ├── phd.png ├── procrastination.png ├── puppet-graph-complex.png ├── rate_of_change.png ├── reconciliation_mechanism.jpg ├── rendered1.png ├── rendered2.png ├── rendered2bis.png ├── rendered3.png ├── rendered4.png ├── rendered_later.png ├── robots1.jpg ├── robots2.jpg ├── sales_funnel.png ├── scribes_copying.jpg ├── separate_activities.jpg ├── single_source_multiple_outputs.png ├── single_sourcing_mechanism.jpg ├── sonar_rules.jpg ├── sonarreference.png ├── source_code_icon.png ├── supplychain.png ├── system_diagram_flottio.png ├── system_diagram_flottio2.png ├── table_code_layout.png ├── timesink.png ├── title_page.png ├── title_page_old.jpg ├── transparent_architecture.png ├── tshirt.jpg ├── type_signature_search.png ├── type_signature_search_int.png ├── uml_class_notation.png ├── useless-uml-diagram.png ├── visible_hygiene.png ├── vo.png ├── what_were_they_thinking.png ├── why_so_complicated.png ├── without_why_same_mistake_again.png ├── wordcloud_bad.png ├── wordcloud_good.png └── zipkin_deps_tracegen.png ├── indexoutline_TODO.txt ├── mainmatter.txt ├── megaphone.png ├── releasenotes_TODO.txt └── update_images.txt /README.md: -------------------------------------------------------------------------------- 1 | # livingdocumentation-thebook 2 | The sources of the Living Documentation book 3 | 4 | # Living Documentation by design, with Domain-Driven Design 5 | Accelerate Delivery Through Continuous Investment on Knowledge 6 | 7 | *by Cyrille Martraire* 8 | 9 | 10 | Get the book on Leanpub: https://leanpub.com/livingdocumentation 11 | 12 | You don't necessarily have to chose between Working Software and Extensive Documentation! Discover how a Living Documentation can help you in all aspects of your projects, from the business goals to the business domain knowledge, architecture and design, processes and deployment, even if you hate writing documentation. 13 | 14 | -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/BiodegradableDoc.txt: -------------------------------------------------------------------------------- 1 | # Biodegradable Documentation 2 | 3 | Biodegradable Documentation 4 | 5 | **Therefore: Consider what it would take for documentation to become unnecessary. This becomes the direction you should move towards.** 6 | 7 | It becomes clear at this point that Living Documentation is not an end in itself, but a mean to an end. Trying to setup a Living Documentation reveals issues about the design, or any other aspect. This becomes an opportunity to improve the root cause, which is above all good for the project and the product, and that in turn makes it possible to have a living documentation, or helps improve the living documentation. Doing that repeatedly leads to a stream of simplifications and standardizations. By this logic, everything becomes so simple and so standard that you don't need documentation any longer. And that would be perfect. 8 | 9 | It does not matter that you actually reach this point or not, but it has to be the goal. The goal of a living documentation initiative is to achieve the level of quality where documentation is mostly unnecessary. The goal of living documentation is not to end up with a lot of beautiful generated diagrams and documents. Instead, they should be considered as workaround solutions or intermediate steps towards better solutions that need less documentation. 10 | 11 | ![Living Documentation long term goal is for documentation to become unnecessary](images/biodegradabledoc.png) 12 | 13 | 14 | My Arolla colleague Khaled Souf once told me of a former experience at a bank: 15 | 16 | > In that bank, I joined a team who took pride in conforming to every standard. I mean market standards, not in-house standards. The result was that I was able to be productive as soon as the first day! Since I knew the technologies and their standard usage, I was immediately familiar on all the project perimeter. No need for documentation, no surprise, no need for any specific customization. 17 | > 18 | > Make no mistake, this was taking a real and continuous effort indeed. Find out the standards, find out the way to solve specific issues while still conforming to standards. This was a deliberate approach, and the benefits were real, for everyone but especially for new joiners! 19 | 20 | In the book *Software Craftsmanship Apprenticeship Patterns*, Dave Hoover and Adewale Oshineye advocate: "Create feedback loops". A living documentation with generated diagrams, glossary, word cloud or any other media is such a feedback look to help criticize what you're doing and to check against your own mental model. This feedback loop becomes particularly useful when your mental model and the content of the generated documents don't match. 21 | -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/DeliberateDesign.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/DeliberateDesign.jpg -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/ExpectedVsActual.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/ExpectedVsActual.jpg -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/LivingDocumentationGoingWild.txt: -------------------------------------------------------------------------------- 1 | # Living Documentation Going Wild 2 | 3 | Living documentation is not a free license to rehash old ideas from the 90's. In particular, beware of the following, which is not Living Documentation: 4 | 5 | - **MDA and everything code generation**: No, code is not a dirty detail to replace or generate, it is the reference and the preferred media whenever we can. Extend your language, or chose a better programming language, instead of generating code from diagrams 6 | 7 | - **Documenting everything, even automatically**: Documenting has a cost, which must be weighted against the benefits. The ideal case is when the code is so self-descriptive it needs nothing else, but even that is not an absolute. Perfection and the quest for purity is often a form of procrastination to be avoided. 8 | 9 | - **UML Obsession**: Some basic UML is fine, but it is not an end in itself. Chose the simplest notation that the intended audience will really understand with as few explanation as possible. Don't obsess on generic notations, problem-specific or domain-specific notations are often more expressive. 10 | 11 | - **Design Patterns Everywhere**: Patterns are good to know, and they help documenting the design through the vocabulary they bring. Don't abuse patterns. It's called "patternitis". Simplicity always first. Perhaps two IF statements are better than a Strategy pattern here! 12 | 13 | - **Analysis Paralysis**: Spending 15 mn all the team together on the whiteboard before each important design decision is time well spent. Spending hours or days is waste. Start with something, anything really. Then it becomes obvious to everyone what's ok and what's not so ok. Now iterate, and take some brief notes Living Documentation-style! 14 | 15 | - **Living Documentation Masterpiece**: Again that's a form of procrastination, when the production work is so boring you escape and work on something more fun instead. Keep in mind Living Documentation is just a mean to help deliver production code, not the other way round. 16 | 17 | - **Documentation before building**: Documentation should reflect what's actually built, more than prescribe what will be built. If your project is interesting, then nothing can beat starting the code. Detailed design specs are waste. Start coding and reflect along the way, collectively, in a just-enough, just-in-time fashion. 18 | -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/Section------BeyondDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 9 Beyond Documentation 2 | -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/biodegradabledoc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/biodegradabledoc.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/curator.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/curator.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/explore-capture-present.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/explore-capture-present.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/fool.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/listen_to_doc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/listen_to_doc.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/over-complicated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/over-complicated.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/visible_hygiene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/visible_hygiene.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/wordcloud_bad.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/wordcloud_bad.png -------------------------------------------------------------------------------- /manuscript/BeyondDocumentation/images/wordcloud_good.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/BeyondDocumentation/images/wordcloud_good.png -------------------------------------------------------------------------------- /manuscript/Biblio.txt: -------------------------------------------------------------------------------- 1 | Read the doc (very nice intro to documentation) 2 | http://docs.writethedocs.org/writing/beginners-guide-to-docs/ 3 | -------------------------------------------------------------------------------- /manuscript/Closing.txt: -------------------------------------------------------------------------------- 1 | # Closing 2 | 3 | If you've read this far, congratulations! You've no graduated on Living Documentation! 4 | 5 | This is just the beginning of the journey. I'd love to hear from you, your feedback, and more importantly your own initiatives on the topic. 6 | 7 | ![](images/phd.png) 8 | 9 | Don't hesitate to get in touch with me, for example via my Twitter handle [@cyriux](https://twitter.com/cyriux). And if you happen to come to Paris, ping me so that we can chat! 10 | -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/3AmigosConversations.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/3AmigosConversations.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/EvenStupidDecisionsHadARationale.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/EvenStupidDecisionsHadARationale.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/MicroservicesAsWalledCitiesMetaphor.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/MicroservicesAsWalledCitiesMetaphor.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/SearchFriendly.txt: -------------------------------------------------------------------------------- 1 | ## Search-Friendly Documentation 2 | 3 | Making information available is not enough. You have to know where to find what you need when you need it, and it's a matter of being easily searchable. 4 | 5 | Being easily searchable is first of all a matter of using distinctive words. 6 | 7 | A> For example, "GO" as a name for a programming language, from a company like Google who is into search, is totally not search friendly. To make it search-friendly again it has to be actually named "golang". 8 | 9 | Then the piece of knowledge should mention clearly the user needs it addresses, since this is the most likely question that will be searched for. To help on this, keywords should be added, including words that don't really occur in the actual content but that are likely to be used when searching for it. Use the words from actual users, found from the analytics of failed searches etc. 10 | 11 | Remember to mention synonyms, antonyms, and faux-sens and common confusions, for improved discoverability by search. 12 | 13 | All this is usually considered only for written text in a traditional document, however this applies just as well in the code, considered as text too. If you use annotations, you may try to add a `keywords = {"insurance policy", "home insurance", "cover"}` to ease full text search on the code. 14 | -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/Section------EfficientDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 11 Efficient Documentation 2 | -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/StackOverflowDocumentation.txt: -------------------------------------------------------------------------------- 1 | # StackOverflow Documentation 2 | 3 | *Don't write all the documentation, let people on SO do it for you.* 4 | 5 | Several times I heard colleagues or even candidates tell that SO is by far the best place to go for documentation, and my experience tends to corroborate this. Official documentation pages are often boring and seldom task-oriented. The funny thing is that people answering on SO often had to use the official documentation pages to build their own knowledge, together with trial and errors or even by having to read the source code sometime. 6 | 7 | People answer questions very quickly on SO. It's another form of *living* documentation: contribute a question, then people all over the world will quickly contribute answers, making the documentation a really living thing. 8 | 9 | **Therefore: When the topic is popular enough, let SO provide a good task-oriented documentation on top of your reference documentation you provided. Let your teams post questions on SO, and let them answer other people's questions as well.** 10 | 11 | This requires your project to be published online, usually with its source code. It especially requires the project to be successful with enough demand to attract contributors. 12 | 13 | Or you can keep it internal and closed source and use an equivalent [on-premises Stack Overflow clones](http://meta.stackexchange.com/questions/2267/stack-exchange-clones). However a domestic Stack Overflow clone may probably miss the scale to work as efficiently as the true worldwide site. 14 | 15 | One downside with Stack Overflow is that if your product is crap it will show. However you can't prevent that happening on the web, unless you make the product better of course. You may also dedicate many employees to answer questions in a positive way to improve a bit the user experience too. 16 | -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/images/areyouawesome.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/images/areyouawesome.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/images/gofastgowell.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/images/gofastgowell.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/images/likecounter.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/images/likecounter.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/images/noprojects_poster.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/images/noprojects_poster.jpg -------------------------------------------------------------------------------- /manuscript/EfficientDocumentation/images/tshirt.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/EfficientDocumentation/images/tshirt.jpg -------------------------------------------------------------------------------- /manuscript/Frontmatter/HowToReadThisBook.txt: -------------------------------------------------------------------------------- 1 | # How to read this book? 2 | 3 | This book is on the topic of Living Documentation, and it is organized as a network of related patterns. Each pattern stands on its own, and can be read independently. However to fully understand and implement a pattern, there is usually the need to have a look at other related patterns, by reading their thumbnail at a minimum. 4 | 5 | I'd like to make this book a *Duplex Book*, a book format suggested by Martin Fowler: The first part of the book is kept short and focuses on a narrative that is meant to be read cover-to-cover. In this form of book, the first part goes through all the content without diving too much into the details, while the rest of the book is the complete list of detailed patterns descriptions. You can read of course this second part upfront, or you may also keep it as a reference to go to whenever needed. 6 | 7 | Unfortunately a Duplex book is hard to do at first try, and the book you are reading at the moment is not one yet. Feel free to skim, dig one area, and read it in any order, though I know readers who enjoyed reading it cover to cover. 8 | -------------------------------------------------------------------------------- /manuscript/Frontmatter/IntroductoryQuestions.txt: -------------------------------------------------------------------------------- 1 | # A simple question 2 | 3 | ## Are you happy with the documentation you create? 4 | 5 | X> yes / no 6 | 7 | When you read documentation material, are you suspicious that it is probably a bit obsolete? 8 | 9 | X> yes / no 10 | 11 | When you use external components, do you wish their documentation was better? 12 | 13 | X> yes / no 14 | 15 | Do you believe that the time you spend doing documentation is time that could be better spent? 16 | 17 | X> yes / no 18 | -------------------------------------------------------------------------------- /manuscript/Frontmatter/NoteToreviewers.txt: -------------------------------------------------------------------------------- 1 | # Note to reviewers 2 | 3 | Many thanks for reading this first version of my book! 4 | 5 | Don't hesitate to share your feedback, even if on one single part or section. 6 | 7 | I especially need feedback on: 8 | 9 | - **What is interesting and needs to be elaborated in more details** 10 | - What is not or less interesting 11 | - **What you strongly disagree with, or you think is plain wrong** 12 | - Suggestions of any additional examples 13 | - Suggestions of any additional illustrations 14 | - More generally, overall feedback on the content more than on form 15 | 16 | Also if you have already put in practice some of the ideas of the book and want to be quoted about it, don't hesitate to tell me about it. 17 | 18 | I know the current book has a lot of : 19 | 20 | - Poorly written sentences (English is not my native language, and the text has not be edited yet) 21 | - Typos (not fully spell-checked yet) 22 | - Low-quality images or too large images 23 | 24 | 25 | Please send all feedback or other comment through the Leanpub feedback form: 26 | 27 | [Leanpub Email the author](https://leanpub.com/livingdocumentation/email_author/new) 28 | 29 | (or at my personal email if you manage to get it :) 30 | 31 | Thanks! 32 | 33 | -- Cyrille 34 | -------------------------------------------------------------------------------- /manuscript/Frontmatter/about.txt: -------------------------------------------------------------------------------- 1 | # About this book 2 | 3 | > "Make very good documentation, without spending time outside of making a better software" 4 | 5 | 6 | The book "Specification by Example" has introduced the idea of a "Living Documentation", where an example of behavior used for documentation is promoted into an automated test. Whenever the test fails, it signals the documentation is no longer in sync with the code so you can just fix that quickly. 7 | 8 | This has shown that it is possible to have useful documentation that doesn't suffer the fate of getting obsolete once written. But we can go much further. 9 | 10 | This book expands on this idea of a Living Documentation, a documentation that evolves at the same pace than the code, for many aspects of a project, from the business goals to the business domain knowledge, architecture and design, processes and deployment. 11 | 12 | This book is kept short, with illustrations and concrete examples. You will learn how to start investing into documentation that is always up to date, at a minimal extra cost thanks to well-crafted artifacts and a reasonable amount of automation. 13 | 14 | You don't necessarily have to chose between Working Software and Extensive Documentation! 15 | -------------------------------------------------------------------------------- /manuscript/Frontmatter/preface.txt: -------------------------------------------------------------------------------- 1 | # Preface 2 | 3 | I never planed to write a book on living documentation. I didn't even have in mind that there was a topic under this name that was worth a book. 4 | 5 | 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 ideas on every occasion, whenever it was helpful in the projects I was working in. 6 | 7 | In 2013 I was speaking at Oredev on Refactoring Specifications. At the end of the talk I mentioned some of the ideas I'd been trying over time, and I had been surprised at the enthusiastic feedback I had around the living documentation ideas. This is when I recognized there was a need for better ways to do documentation. I've done this talk again since then and again the feedback was about the documentation thing and how to improve it, how to make it realtime, automated and without manual effort. 8 | 9 | By the way, the word Living Documentation was introduced on the book Specifications by Example by Gojko Adzic, as one of the many benefits of Specifications by Example. Living Documentation is a good name for an idea which is not limited to specifications. 10 | 11 | There was a topic, and I had many ideas to share about it. I wrote down a list of all these things I had tried, plus other stuff I had learnt around the topic. More ideas came from other people, people I know and people I only know from Twitter. As all that was growing I decided to make it into a book. Instead of offering a framework ready for use, I believe a book will be more useful to help you create quick and custom solutions to make your own Living Documentation. 12 | -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/ProjectVsSystem.txt: -------------------------------------------------------------------------------- 1 | ## Project vs. System Segregation 2 | 3 | It's important to clarify is the distinction between a project and a system. A project builds or changes a system. A project starts, stops, has a purpose, a team, stakeholders, and a budget. A system exists, also has a vision, purpose, users and stakeholders, and is made of components or services on top of infrastructures. A system exhibits behaviors and has quality attributes. 4 | 5 | > The distinction is the same as the distinction between a balance sheet and a general ledger. The balance sheet describes the overall effect (the system) of all the transactions on the ledger (the projects). At the end of the year, we only care about the balance sheet, not about each individual transaction. 6 | 7 | The system and the project only match in the case of the first project whose sole goal is to build a system from scratch. But there are many other situations than this simple case, many systems go through more than one project over their lifetime, and even their death is yet another project. 8 | 9 | It is important not to mix the knowledge about the project vs. the knowledge about the system. The knowledge about the project is only useful for the duration of the project, but the knowledge about the system is useful throughout the life of the system. 10 | 11 | In general, focus on documenting the knowledge about the system, as the lifetime of the system will far exceed the lifetime of the project. Overall, the system design far outlives the user stories which built it in the first place. After some time, you need to understand the system, and nobody (except auditors) cares how the user stories were split and prioritized. 12 | 13 | > ## An Example 14 | > 15 | > Keep all the knowledge about the project planning, teams and management in Jira, and use internal documentation for all the knowledge about the system. 16 | > 17 | > Releases, Iterations and User stories are project artifacts. Use stickers on the wall or a tool like Jira for them. At the time of coding the system, you create key scenarios (or acceptance criteria) and you write the code. These are knowledge about the system, which is best expressed as Internal documentation, in the source control, as automated scenarios (tests) and other means as shown in this book. 18 | > 19 | > Notice that the sentences on the user story: "In order to... As a... I want..." will often end up as the narrative on top of your key scenarios files in the source control. This little duplication ensures that the system owns all its documentation in a standalone fashion. The source code repository is self-documented without the tracker. 20 | -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/Section------IntroducingLivingDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 12 Introducing Living Documentation 2 | -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/SkillsMatrix.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/SkillsMatrix.jpeg -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_annotation_registry.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_annotation_registry.jpg -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_bad_modules.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_bad_modules.jpg -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_bubble_context.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_bubble_context.jpg -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_expected_vs_actual.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_expected_vs_actual.jpg -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_expected_vs_actual.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_expected_vs_actual.png -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_modules_mapping.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_modules_mapping.jpg -------------------------------------------------------------------------------- /manuscript/IntroducingLivingDocumentation/images/legacy_strangled_app.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/IntroducingLivingDocumentation/images/legacy_strangled_app.jpg -------------------------------------------------------------------------------- /manuscript/Introduction/AllAboutKnowledge.txt: -------------------------------------------------------------------------------- 1 | # It's all about knowledge 2 | 3 | It'a all about knowledge. Software development is all about knowledge, and decision-making based on it, which in turn becomes additional knowledge. The given problem, the decision that was made, the reason why it was made that way, and the facts that led to this decision, and the considered alternative are all knowledge. 4 | 5 | You may not think about it that way, but each instruction typed in a programming language is a decision. There are big and small decisions, but it's just decisions taken. In software development, there is no expensive construction phase following a design phase: the construction is so cheap (running the compiler) that there's only an expensive, sometime everlasting, design phase. 6 | 7 | This design activity can last for a long time. It can last long enough to forget about previous decisions made, and their context. It can last long enough for people to leave, with their knowledge, and for new people to join, with missing knowledge. Knowledge is central to a design activity like software development. 8 | 9 | This design activity is also most of the time, and for many good reasons, a teamwork, with more than one person involved. Working together means taking decisions together or taking decisions based on someone else's knowledge. 10 | 11 | Something unique with software development is that the design involves not only people but also machines. Computers are part of the picture, and many of the decisions taken are simply told to the computer to execute. It's usually done through documents that are called "source code". Using a formal language like a programming language, we pass knowledge and decisions to the computer in a form it can understand. 12 | 13 | Having the computer understand the source code is not the hard part though. Even unexperienced developers usually manage to succeed at that. The hardest part is for other people to understand what has been done, in order to do a better and faster work. 14 | 15 | The larger the ambition, the more documentation becomes necessary to enable a cumulative process of knowledge management that scales beyond what fits in our heads. When our brains and memories are not enough, we need assistance from technologies like writing, printing, and software to help remember and organize larger sets of knowledge. 16 | -------------------------------------------------------------------------------- /manuscript/Introduction/Fun.txt: -------------------------------------------------------------------------------- 1 | # Fun 2 | 3 | Fun is important for sustainable practices. If it's not fun, you'll not want to do it so often and the practice will progressively disappear. For practices to last, they'd better be fun. It's particularly important on so boring a topic like documentation. 4 | 5 | **Therefore: Chose practices that help satisfy the needs according to the principles, while being as fun as possible. If it's fun, do more of it, and if it's totally not fun, look for alternatives, like solving the problem in another way or through automation.** 6 | 7 | This assumes that working with people is fun, because there's no good way around that. For example, if coding is fun, we'll try to document as much as possible in code. That's the idea behind many suggestions in this book. If copying information from one place to another is a chore, then it's a candidate for automation, or for finding a way for not having to move data at all. Fixing the process or automating a part of it are more fun, so we're back to something that we feel like doing. That's lucky. 8 | 9 | ![Fun starts with automating the chores](images/chore_automation.png) 10 | 11 | A> ## A rant that is not fun 12 | A> 13 | A> One more thing: there's nothing wrong with having fun at work, as long as we're professional in our work. This means doing our best to solve the problems that matter, delivering value, reducing risk. With that in mind, we're free to chose the practices and tools that make our life more fun. After 15 years in programming I'm now confident it's always possible to do professional work while having fun. The idea that work should be boring and unpleasant because it's work, or because we're paid for it to compensate for this very unpleasantness, is just stupid. We're paid some money to deliver value worth even more money. Delivering value is fun, and behaving professionally is pleasant too. And fun is essential for working efficiently as a team, in a pleasant atmosphere. 14 | -------------------------------------------------------------------------------- /manuscript/Introduction/KnowledgeIsAlreadyThere.txt: -------------------------------------------------------------------------------- 1 | # Knowledge is already there 2 | 3 | Every interesting project is a learning journey to some extent, producing specific knowledge. We usually expect documentation to give us the specific knowledge we need, however the funny thing is that all this knowledge is already there: in the source code, in the configuration files, in the tests, in the behavior of the application at runtime, in memory of the various tools involved, and of course in the brain of all the people working on it. 4 | 5 | > ## Knowledge is already there 6 | > 7 | > In a software project most of the knowledge is present in some form somewhere in the artifacts. 8 | 9 | The knowledge is there somewhere, but this does not mean that there is nothing to do about it. There are a number of problems with the knowledge that's already there. 10 | 11 | **Not Accessible**: The knowledge stored in the source code and other artifacts is not accessible to non technical people. For example, source code is not readable by non developers. 12 | 13 | **Too Abundant**: All the knowledge stored in the project artifacts is in huge amounts, which makes it not usable efficiently. For example, each logical line of code encodes knowledge, but for a given question, only one or two lines may be relevant to give the answer. 14 | 15 | **Fragmented**: There is knowledge that we think of as one single piece but that is in fact spread over multiple places in the projects artifacts. For example, a class hierarchy in Java is usually spread over multiple files, one for each subclass, even if we think about the class hierarchy as a whole. 16 | 17 | **Implicit**: A lot of knowledge is present but implicitly in the existing artifacts. It's 99% there, but is missing the one more 1% to make it explicit. For example when you use a design pattern like a Composite, the pattern is visible in the code, but only if you're familiar with the pattern. 18 | 19 | **Unrecoverable**: It happens that the knowledge is there but there is no way to recover it because it's excessively obfuscated. For example business logic is expressed in code but the code is so bad that nobody can understand it. 20 | 21 | **Unwritten**: In the worst case, the knowledge is only in people's brain, and only its consequences are there in the system. For example, there is a general business rule but it has been programmed as a series of special cases, so the general rule is not expressed anywhere. 22 | -------------------------------------------------------------------------------- /manuscript/Introduction/KnowledgeOrigination.txt: -------------------------------------------------------------------------------- 1 | # Knowledge origination 2 | 3 | Where does knowledge come from? 4 | 5 | Knowledge primarily comes from **conversations**. We develop a lot of knowledge through conversations with other people. This happen during collective work like pair programming, or during meetings, or at the coffee machine, on the phone, or via a company chat or emails. 6 | 7 | Examples: BDD specification workshops, 3 amigos, concrete examples 8 | 9 | However as software developers we have conversations with machines too, which we call **experiments**. We tell something to the machine in the form of code in some programming language, and the machine runs it and tells us something in return: the test fails or goes green, the UI reacts as expected, or the result is not what we wanted, in which case we'll learn something new. 10 | 11 | Examples: TDD, Emerging Design, Lean Startup experiments 12 | 13 | Knowledge also comes from observation of the context. In a company you learn a lot by just being there, listening to other people conversations, behavior and emotions. 14 | 15 | Examples: Domain Immersion, Obsession Walls, Information Radiators, Lean Startup "Get out of the building" 16 | 17 | > ## Conversations, Experiments, Context 18 | > 19 | > Knowledge comes from conversations with people and experiments with machines in an observable context. 20 | 21 | 22 | 23 | ## How does that knowledge evolve? 24 | 25 | Some knowledge is stable in years, whereas other is living all the time, over months or even over hours. 26 | 27 | This means that whatever we do about documentation has to consider the cost of maintenance, and to make it as close to zero as possible. For stable knowledge everything's simple, and traditional methods of documentation work. But in most cases the knowledge is changing frequently enough that writing text and updating it on every change is just not an option. 28 | 29 | The effect of acceleration in the software industry means that we want to be in a position to evolve the software so quickly that it's obviously impossible to spend time writing pages and pages of documentation. And yet we want all the benefits of documentation. 30 | -------------------------------------------------------------------------------- /manuscript/Introduction/Section------Introduction.txt: -------------------------------------------------------------------------------- 1 | -# Part 1 Reconsidering Documentation 2 | -------------------------------------------------------------------------------- /manuscript/Introduction/images/4-principles.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/4-principles.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/4_principles.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/4_principles.jpg -------------------------------------------------------------------------------- /manuscript/Introduction/images/brain_dump.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/brain_dump.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/chore_automation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/chore_automation.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/copist.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/copist.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/living_documentation_map.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/living_documentation_map.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/misleading_label.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/misleading_label.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/out_of_sync.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/out_of_sync.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/procrastination.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/procrastination.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/rate_of_change.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/rate_of_change.png -------------------------------------------------------------------------------- /manuscript/Introduction/images/separate_activities-old.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/separate_activities-old.jpg -------------------------------------------------------------------------------- /manuscript/Introduction/images/separate_activities.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/separate_activities.jpg -------------------------------------------------------------------------------- /manuscript/Introduction/images/timesink.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction/images/timesink.png -------------------------------------------------------------------------------- /manuscript/Introduction_Overview/SpineModel.txt: -------------------------------------------------------------------------------- 1 | # A principled approach 2 | 3 | To better organize what is Living Documentation, its values and principles, here's the [The Spine Model](http://spine.wiki/explanation/introduction/) for it. It starts with stating the need we acknowledge and that we decide to address. Then we clarify the main values that we want to optimize for. A list of principles follows, and is there to help change the current situation. 4 | 5 | By keeping the needs, the main values and the principles in mind, in this order of importance, we can then apply practices and use tools to get the work done in an effective fashion. 6 | 7 | ## Need 8 | 9 | **Evolve software continuously, collectively and over the long run.** 10 | 11 | We want to deliver software quickly now, and at least as quickly in the future. We need to collaborate as a team, and when necessary with even more people who can't always meet at the same time or at the same place. 12 | 13 | We want to take the best possible decisions based on the most relevant knowledge, in order to make the work on the software sustainable in the long run. 14 | 15 | ## Values 16 | 17 | We optimize for the following values: 18 | 19 | 1. Deliberate Thinking 20 | 1. Continuous Knowledge Sharing 21 | 1. Fruitful Collaboration 22 | 1. Honest Feedback 23 | 1. Fun 24 | 25 | ## Principles 26 | 27 | We leverage the following principles to change the way we work: 28 | 29 | 1. Conversations over Documents 30 | 1. Most Knowledge is Already There 31 | 1. Internal Documentation over External Documentation 32 | 1. Automate for the long term 33 | 1. Enforced Accuracy 34 | 1. Single Source of Truth 35 | 1. Working Collectively 36 | 1. Documentation is also at Runtime 37 | 1. Documentation is Communication 38 | 1. Segregation by Pace of Change 39 | 1. Make Documentation Unnecessary 40 | 1. A Whole Activity (carefully done, with multiple benefits) 41 | 42 | ## Practices 43 | 44 | We have the following practices available to deliver value: 45 | 46 | - Living Diagram 47 | - Living Glossary 48 | - Declarative Automation 49 | - Enforced Guidelines 50 | - Small-Scale Model 51 | - and many others that are the focus of this book. 52 | 53 | ## Tools 54 | 55 | To get the work done, we use tools. Most of them are primarily mental tools, but tools that we can download also help of course! 56 | 57 | There are many tools of interest for a Living Documentation, and they evolve quickly. This list of tools starts with your regular programming languages, and extends to automation tools on top of your practice of BDD, like Cucumber or SpecFlow, and includes rendering engines for Markdown or AsciiDoc, and automatic layout engine for diagrams like Graphviz. 58 | -------------------------------------------------------------------------------- /manuscript/Introduction_Overview/_checklist_diagram.txt: -------------------------------------------------------------------------------- 1 | # No Documentation Checklist // reducing the waste 2 | 3 | %% to render, e.g at http://sandbox.kidstrythisathome.com/erdos/ 4 | 5 | root [label="I want more documentation!"]; 6 | why [label="why?"]; 7 | who [label="who?"]; 8 | need [label="do we really need it?"]; 9 | trust [label=" trust?"]; 10 | std [label=" standard? -> Focus on specific knowledge"]; 11 | now [label="do we really need it now? -> JIT, Cheap Option, Upfront, For Review"]; 12 | talking [label="Conversation & Working together is enough?"]; 13 | keep [label="Persistent? Large Audience? Critical?"]; 14 | written [label="Written & Self Documented Artifacts!"]; 15 | 16 | root -> why; 17 | why -> who; 18 | who -> need; 19 | need -> trust; 20 | need -> std; 21 | std -> now; 22 | now -> talking; 23 | now -> keep; 24 | keep -> written; 25 | -- 26 | # Knowledge Exploitation & Augmentation Checklist // knowledge already there 27 | 28 | Where's the knowledge right now? 29 | In people's head? -> encode somewhere as text, code, metadata etc. 30 | Already represented? 31 | 32 | exploitable, or obfuscated or unrecoverable? 33 | too abundant? 34 | accessible for the intended audience? 35 | in one single place or fragmented? 36 | What's missing to make it 100% explicit? 37 | 38 | -- 39 | # Knowledge Evolution // maintenance, stable vs. volatile 40 | 41 | How stable is this knowledge? 42 | If it changes, what does change at the same time? 43 | If there's a redundant knowledge, how to make the redundant sources in sync? 44 | -------------------------------------------------------------------------------- /manuscript/Introduction_Overview/images/color-coded-pompidou.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/Introduction_Overview/images/color-coded-pompidou.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/HighlightedCore.txt: -------------------------------------------------------------------------------- 1 | # Highlighted Core (Eric Evans) 2 | 3 | %% curation 4 | %% code digest 5 | 6 | *Some elements of the domain are more important than others* 7 | 8 | In the book Domain-Driven Design, Eric Evans explains that when a domain grows to a large number of elements, it becomes difficult to understand, even if only a small subset of them are really important. A simple way to guide developers focus on these particular subset is to highlight it in the code repository itself. 9 | 10 | **Flag each element of the CORE DOMAIN within the primary repository of the model, without particularly trying to elucidate its role. Make it effortless for a developer to know what is in or out of the CORE.** 11 | 12 | Using annotations to flag the core concepts directly into the code is a natural approach, one which evolves well over time. Code elements like classes or interfaces get renamed, move from one module to another, and sometime end up deleted. 13 | 14 | ~~~~~~~~ 15 | /** 16 | * A fuel card with its type, id, holder name 17 | */ 18 | @ValueObject 19 | @CoreConcept 20 | public class FueldCard { 21 | private final String id; 22 | private final String name; 23 | ... 24 | ~~~~~~~~ 25 | 26 | This is a perfect simple example of curation by annotations. It is an internal documentation integrated into the search capabilities of your IDE. You can see the list of all core concepts just by searching every reference of the annotation in the project, always up to date. 27 | 28 | ![The highlighted core is available instantly and at any time in your IDE through a search on all references of the @CoreConcept annotation](images/highlighted_core_eclipse_search.png) 29 | 30 | And of course, tools can also scan the source and use the highlighted core as a convenient and relevant way to improve their curation. For example, a tool to generate a diagram may show everything when there are less than 7 elements, and focus only on the highlighted core when there are many more elements. A living glossary typically uses that to highlight the most important elements in the glossary too, by showing them first, or by printing them in a bold font. 31 | -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/IntrinsicKnowledgeAugmentation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/IntrinsicKnowledgeAugmentation.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/MachineAccessibleDocumentation.txt: -------------------------------------------------------------------------------- 1 | # Machine Accessible Documentation 2 | 3 | *Documentation that is machine-accessible opens new opportunities for tools to help at design level* 4 | 5 | You code at design level, not just code level, but your tools cannot help you much at design level. They cannot help because they have no idea what you are doing on the design perspective from the code alone. If you make your design explicit, for example using annotations attached to the code, then tools can begin to manipulate the code at the design level too, and help you more. 6 | 7 | Design knowledge that can make the code more explicit is worth adding. An annotations attached to the language element is often enough, e.g. you can declare the layers on each top-level package, in the corresponding package-info.java file: 8 | 9 | @Layer(LayerType.INFRASTRUCTURE) 10 | package com.example.infrastructure; 11 | 12 | By putting the annotation @Layer on the package com.example.infrastructure, you declare a particular instance of the pattern Layer, where the layer is the package itself. 13 | 14 | As usual there are many options to design a custom annotation, like this declaring an id (this may be useful to reference it later): 15 | 16 | @Layer(id = "repositories") 17 | package com.example.domain; 18 | 19 | With this design intent made explicit in the code itself, tools like a dependency checker could now automatically derive forbidden dependencies between layers, to detect when they are violated. 20 | 21 | You could do that with tools like JDpend, but you'd have to declare each package-to-package dependency restriction. This it tedious and does not directly describes the layering, just the consequence of the layering. 22 | 23 | Declaring every forbidden or acceptable package-to-package dependency is tedious, but now imagine doing it between classes: it's prohibitive! However, if classes are tagged, e.g. as @ValueObject, @Entity or @DomainService, now dependency checkers can enforce our favorite dependency restrictions. For example I like to enforce the following rules: 24 | 25 | Value Objects should never depend on anything other than other Value Objects. 26 | Entities should never have any Service instance as member field. 27 | 28 | Once the classes are augmented with these stereotypes explicitly, we could now tell the tools what we want more literally and more concisely. 29 | -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/_DocumentationByDSL.txt: -------------------------------------------------------------------------------- 1 | # Documentation by Meta-Model 2 | 3 | *Sometime the best media to describe code is just code.* 4 | 5 | Compared to free text, code has many advantages: it's structured, offers auto-completion thanks to your IDE, is checked by the compiler, can itself be documented and annotated, and still has all the benefits of being plain text. 6 | 7 | This makes code a great tool for documentation purposes! 8 | 9 | Example with Adrian Cockroft Spigo DSL as Json: https://github.com/adrianco/spigo/tree/master/json_arch 10 | 11 | --- 12 | 13 | As an example, let's describe a full Information System using code as a model. We'll see how we can even use this model to reason about our system and its testing strategy. 14 | 15 | ~~~~~~~~ 16 | describeInformationSystem() 17 | 18 | Service 19 | Component 20 | 21 | InformationSystem 22 | EndUserApp 23 | FrontService 24 | BackEndService 25 | DataStore 26 | ~~~~~~~~ 27 | 28 | %% TODO insert Simon Brown example 29 | -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/_DocumentationRegistry.txt: -------------------------------------------------------------------------------- 1 | Tags in the discovery server (Consul) 2 | 3 | 4 | TO MOVE TO Sidecar_file_MetaDB.txt 5 | 6 | - QueryModel 7 | - CommandService 8 | 9 | - BackEndForFrontEnd 10 | - Cache 11 | - ReverseProxy 12 | - Projection 13 | -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/_ExtendTheLiterature.txt: -------------------------------------------------------------------------------- 1 | # Extend the literature 2 | 3 | Got new reusable knowledge worth documenting? 4 | 5 | - Generic knowledge is worth sharing 6 | - The pattern format (or just a blog post) 7 | - Open Space sessions to nurture ideas 8 | - Patterns workshops to improve 9 | - Why not sharing to the outside audience? (blog, conference talk...) 10 | 11 | 12 | Standard Knowledge over Custom Folklore 13 | -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/annotation_tooltip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/annotation_tooltip.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/augmented_code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/augmented_code.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/exemplar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/exemplar.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/fool.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/github_blame_view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/github_blame_view.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/highlighted_core_eclipse_search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/highlighted_core_eclipse_search.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/what_were_they_thinking.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/what_were_they_thinking.png -------------------------------------------------------------------------------- /manuscript/KnowledgeAugmentation/images/without_why_same_mistake_again.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeAugmentation/images/without_why_same_mistake_again.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/OneArtifactMultipleUses.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/OneArtifactMultipleUses.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/OneManuscriptMultipleDerivatives.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/OneManuscriptMultipleDerivatives.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/ReadyMadeKnowledge_patterns_criticism.txt: -------------------------------------------------------------------------------- 1 | D> ## Gut feeling and spontaneity 2 | D> 3 | D>Since when knowing something consciously should be considered less desirable than just gut-feeling? 4 | D> 5 | D> This is however one of the various kinds of criticisms about patterns out there, and this one is clearly explained in an interesting post from Steve: 6 | 7 | D> *The use of patterns is like the use of literary device. There are (probably) an infinite number of ways in which the same general thought can be expressed, but I doubt you will find a single quality writer who started off a chapter thinking, "I'm introducing a character here so it's best to paint a picture of the character. That calls for simile. Yeah, simile will do it. I think I'll also use some ironic juxtaposition.” This type of writing feels forced. I've read code where the application of design patterns also felt forced.* 8 | D> 9 | D> Steve has a point here. I must admit that gut feeling, if trained properly on examples of good quality, may have advantages over a conscious quest for perfection, perhaps because our brain is more powerful that we can ever be conscious of. And yes, very often, we pretend that what we did was intentional and deliberate whereas we're just explaining a posteriori a decision that was actually based on gut feeling. 10 | D> 11 | D> Then Francois from the ORM *Propel* raised the topic: should developers know design-patterns? He discusses in a blog post the reasons to mention or not the various patterns used at the heart of the Propel ORM in the documentation of the engine. 12 | D> 13 | D> ORM engines are rather sophisticated pieces of software, and they make big (and deliberate) use of patterns, in particular the Fowler PoEAA patterns: 14 | D> 15 | D> *Propel, like other ORMs, implements a lot of common Design Patterns. Active Record, Unit Of Work, Identity Map, Lazy Load, Foreign Key Mapping, Concrete Table Inheritance, Query Object, to name a few, all appear in Propel. The very idea of an Object-Relational Mapping is indeed a Design Pattern itself.* 16 | D> 17 | D> If you know the patterns, you can understand Propel quickly; if you don't, then you'll need to go through much more explanations to reach the same level of expertise. And next time you'll encounter another ORM you'll have to redo this discovery effort. Of course at some point you'll recognize the patterns, and you just won't know their names. You'd just be half-conscious of the patterns. 18 | D> 19 | -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/Section------KnowledgeExploitationAugmentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 3 Knowledge Exploitation & Augmentation 2 | -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/_HumaneRegistry.txt: -------------------------------------------------------------------------------- 1 | ## Humane Registry 2 | Martin Fowler 3 | 4 | Wiki with contributions from both devs and users + auto-fed information from source control, usage tracking... 5 | -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/ConsolidatedView.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/ConsolidatedView.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/JB1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/JB1.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/JB2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/JB2.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/JB3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/JB3.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/JB4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/JB4.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/Reconciliation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/Reconciliation.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/Reconciliation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/Reconciliation.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/consolidation_mechanism.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/consolidation_mechanism.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/element_of_a_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/element_of_a_system.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/reconciliation_mechanism.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/reconciliation_mechanism.jpg -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/single_source_multiple_outputs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/single_source_multiple_outputs.png -------------------------------------------------------------------------------- /manuscript/KnowledgeExploitation/images/single_sourcing_mechanism.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/KnowledgeExploitation/images/single_sourcing_mechanism.jpg -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/Section------LivingDesignArchitecture.txt: -------------------------------------------------------------------------------- 1 | -# Part 10 Living Design & Architecture Documentation 2 | -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/_service_registry.txt: -------------------------------------------------------------------------------- 1 | # Living Arch - # Documentation by Registry (Consul / Eureka) 2 | 3 | Platform-level source repository (Github) 4 | README, guidelines etc. 5 | Timeline service 6 | 7 | Distributed Tracing (e.g. Zipkin) 8 | Distributed Tracing annotations // augmentation 9 | Daily Aggregation of Distributed Traces //dependencies 10 | 11 | Discovery Registry (e.g. Consul) 12 | Discovery Registry tags // augmentation: Read / Write Model, Service / Data Pump / BFF / API Gateway, Infra, Bounded Context, Proxy, Legacy, Adapter 13 | 14 | Living Diagrams 15 | by Front - Back, 16 | by Back && Bounded Context(services, data pumps…) 17 | by Front && Audience (BFF, Gateway, Front Service like Search, TODO etc.) 18 | by Domain && Service only, Infra only, 19 | by integration (Proxy, Adapter, BFF, Pump), 20 | Runtime Conformity Checker (Simian Army) 21 | Consumer-Driven Contracts 22 | 23 | 24 | spring: 25 | cloud: 26 | consul: 27 | discovery: 28 | tags: foo=bar, baz 29 | -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/ReadyForExtension.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/ReadyForExtension.jpg -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/codex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/codex.png -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/fool.png -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/james_lewis_cloud_diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/james_lewis_cloud_diagram.png -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/megaphone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/megaphone.png -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/sales_funnel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/sales_funnel.png -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/transparent_architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/transparent_architecture.png -------------------------------------------------------------------------------- /manuscript/LivingDesignArchitecture/images/why_so_complicated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDesignArchitecture/images/why_so_complicated.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/LivingDocument.txt: -------------------------------------------------------------------------------- 1 | # Living Document 2 | 3 | *A document that is evolving at the same pace than the system it describes* 4 | 5 | **A living document is a document that is evolving at the same pace than the system it describes. It's prohibitively time-consuming to do manually, hence it's usually achieved through automation.** 6 | 7 | As the names suggest Living documentation relies a lot on living documents, whenever Code as Documentation, Evergreen Documents and Tools History are not enough. 8 | 9 | A living document works like a reporting tool that produces a new report after each change. A change is usually a code change, but could be just a key decision done during a conversation. 10 | 11 | In this chapter we'll present a few key examples of Living Documents, like Living Glossary and Living Diagram. 12 | 13 | ## Anatomy of a living document. 14 | 15 | A Living Document typically works in 4 main steps: 16 | 17 | 1. Select a range of data stored somewhere, for example source code in source control 18 | 1. Filter the data according to the objective of the document 19 | 1. For each piece of data that made it out through the filter, extract the subset of its content that is of interest for the document. It can be seen as a projection, and it's totally specific to the purpose of the diagram 20 | 1. Convert the data, and their relationships into the target format to produce the document. For a visual document it can the API of the rendering library. For a text document it can be a list of text snippets, or the library to produce a PDF. 21 | 22 | If the rendering is very complex, the last step of converting into another model may be done twice, by creating an intermediate model that is then used to drive the final rendering library. 23 | 24 | The hard part in each step is the interplay between the Editorial Perspective and the Presentation Rules. What data to select or ignore? What information to add from another source? What layout? 25 | 26 | ## Presentation Rules 27 | 28 | There are rules for a good document, such as showing or listing no more than 7+/-2 items at a time. There are also rules for choosing a particular layout, a list or a table or chart so that it is congruent with the structure of the problem. This is not a book on that topic, however some awareness on these presentation rules will help you make your documents more efficient. 29 | -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/PatternOrientedLivingDiagram.txt: -------------------------------------------------------------------------------- 1 | ## Pattern-Oriented Living Diagram 2 | 3 | ### The challenges with automated generation of design documentation 4 | 5 | Producing a documentation of the design of a software project manually requires a lot of work, and becomes obsolete very quickly after the next change or refactoring. Manually drawing meaningful UML diagrams is very time consuming, and even choosing what to display takes a lot of time. 6 | 7 | As Domain-Driven Design states, the code is itself the model, but code lacks the ability to clearly express larger-than-class structures and collaborations. This is why some additional carefully selected design documentation is useful to show the bigger picture. And it can be generated from the code, as long as the code is augmented with the design intentions. 8 | 9 | ### Generating design documentation 10 | 11 | The use of patterns to help with the process of generating a design documentation is promising. Patterns naturally lie "on top" of the language elements. They address a particular problem within a context, discuss a solution and have a clear intent. They involve a collaboration of several elements from the language, such as several classes and their protocol, or just relations between fields and methods within a class. Each pattern is a chunk of design knowledge. When comes the time to automate the description of the design, it sounds natural to chunk the automation process by pattern as well. 12 | 13 | In past projects I've declared some of the patterns used in the code (using annotations), and created little tools derive from them partial macro structures of the software design around these patterns. Since each pattern come with a context, this context helps for selecting what to show or hide, and how to show it. 14 | 15 | From the patterns declared in the code, the tool can then generate a better-than-generic design documentation (e.g. diagram) informed by the knowledge chunked pattern by pattern. 16 | -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/Section------LivingDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 4 Automated Documentation 2 | -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/_LivingContextMap.txt: -------------------------------------------------------------------------------- 1 | # Living Context Map Diagram 2 | 3 | %% TODO CODE 4 | 5 | Don't confuse between Data flow, who's calling who, and who's using the service vs providing the service. 6 | 7 | Also keep in mind that Context Mapping is a diagnosis tool, not a way to define a target situation. In this view it makes sense to derive as much as possible of the Context Mapping from the actual artifacts. 8 | 9 | The presence of a Bounded Context is always characterized by an artifact like a module of code, an XML schema or a DB schema, but you usually need to make it explicit. 10 | 11 | You may need naming conventions, regex filtering, annotations to augment the code with Bounded Context declarations. In practice, projects which are consistent in their conventions and style may at least enumerate the list of all Bounded Contexts involved. If this enables the automated creation of an automated inventory of Bounded Contexts, that's very good news for the maintenance of the Context Map: even if you need to add explicit declaration for each of them, at least you have a way to highlight those that don't have a declaration yet. Whenever a new Bounded Context appears, it will show up in the list without a declaration, so you know you have to so something. 12 | 13 | A Context Map is a diagram which shows the various Bounded Contexts and the Strategic patterns between them. 14 | 15 | The presence of a relationship between two Bounded Contexts can often be derived: there's a dependency between code to code, code to schema or schema to schema. Unfortunately as far as I know, the upstream or downstream relationship direction has to be declared. It's obvious for humans to tell who's providing value to the other, but it's almost impossible for machines to guess that accurately. The exact relationship pattern has to be declared too: Conformist, or Customer-Supplier, or Partnership? 16 | 17 | We may still derive some partial information from the artifacts in order to create a Context Map. For example, AntiCorruption Layers (ACL) hardly ever happen by random luck. Therefore having dependencies but no declared ACL likely signals a Conformist relationship. 18 | 19 | Some Bounded Contexts are harder to identify since there may be no code for them; that's definitely the case for Interchange Context, which are defined as a schema or as a norm, perhaps outside of your company: MIME types, Json or XML schema, DB schemas, standard file formats: png, mp3... 20 | -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/_LivingDiagramExamplesList.txt: -------------------------------------------------------------------------------- 1 | 2 | @abdullin: Our auto-generated domain diagrams got awesome feature from @pjvds: show events that are subscribed but not tested. http://t.co/FtpS4QGsSH 3 | 4 | 5 | 6 | ## Living Diagram examples 7 | 8 | - Sub-types of a type: FixedIncome <- Bond, Swap, Future, FRA // built-I'm most IDE on-demand 9 | - Message / debugging object graph (quasi actual example) 10 | - circle of a cyclic group Rock > Scissor > Paper > Rock 11 | - Tree of hierarchical config file entries (log.properties) // not sure it's very useful 12 | - runtime test results chart // payments over time 13 | - physical view from code written for that purpose // see blog using neo4j to graph 14 | (- pattern with its collaborators) 15 | - core domain / abstract core 16 | - hexagonal architecture 17 | - tribe around a concept // close to aggregate 18 | - context mapping // from annotations? Misses the point of a diagnostic tool 19 | (the sound of Fizzbuzz) 20 | -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/alistair_hexagonal.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/alistair_hexagonal.gif -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/bc1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/bc1.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/bc2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/bc2.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/cash_timeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/cash_timeline.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/domain-specific-svg1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/domain-specific-svg1.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/domain-specific-svg2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/domain-specific-svg2.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/element_of_a_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/element_of_a_system.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/enum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/enum.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/fool.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/hexagonal-sketch.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/hexagonal-sketch.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/hexagonal.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/hexagonal.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/hexagonal_living-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/hexagonal_living-diagram.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/hexagonal_living-diagram.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/hexagonal_living-diagram.tif -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/living-diagram1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/living-diagram1.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/living-diagram2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/living-diagram2.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/living_diagram_overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/living_diagram_overview.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/musictheory_treeview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/musictheory_treeview.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/one-diagram-one-story.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/one-diagram-one-story.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/orderbook_table.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/orderbook_table.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/overview.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/overview.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/package-annotations.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/package-annotations.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/packages.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/packages.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/pasted-image-6633.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/pasted-image-6633.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/policy_timeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/policy_timeline.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/rendered1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/rendered1.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/rendered2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/rendered2.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/rendered2bis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/rendered2bis.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/rendered3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/rendered3.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/rendered4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/rendered4.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/rendered_later.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/rendered_later.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/supply-chain-geo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/supply-chain-geo.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/supply-chain-timeline.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/supply-chain-timeline.jpg -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/supplychain.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/supplychain.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/system_diagram_flottio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/system_diagram_flottio.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/system_diagram_flottio2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/system_diagram_flottio2.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/useless-uml-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/useless-uml-diagram.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/vo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/vo.png -------------------------------------------------------------------------------- /manuscript/LivingDocumentation/images/zipkin_deps_tracegen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/LivingDocumentation/images/zipkin_deps_tracegen.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/ContinuousTraining.txt: -------------------------------------------------------------------------------- 1 | ## Continuous Training 2 | 3 | As general knowledge becomes more widespread, the less you need to document in average. Investing in continuous training is therefore a way to lower the need for documentation. 4 | 5 | Learning standard skills also makes it more likely to use more ready-made knowledge at the expense of original solutions. This is good the quality of the solution and because it alleviates the need for specific documentation. 6 | 7 | More consistency of skills and shared culture also helps faster decision-making. It's not about removing all diversity in the team, since diversity is an essential ingredient. Still, we don't need all diversity in every detail, and there's a lot that we can make more consistent without loosing much. 8 | 9 | Investing in continuous training can be done with: 10 | 11 | - Coding Dojos on code kata, e.g at lunch time every Friday 12 | - Short Training sessions during the day 13 | - Interactive Mini-Trainings, e.g. half an hour twice a week right after lunch 14 | - Time for deliberate practice, e.g. 20% time policy. 15 | -------------------------------------------------------------------------------- /manuscript/NoDocumentation/MakingMistakesImpossible.txt: -------------------------------------------------------------------------------- 1 | ## Making Mistakes Impossible - Error-Proof API 2 | 3 | *Design your API in a way that makes it impossible to misuse. This reduces the need for documentation, since there's nothing to warn the user of.* 4 | 5 | Michael L Perry listed many common API traps in a [blog post](http://qedcode.com/practice/provable-apis.html): 6 | 7 | - You must set a property before calling this method 8 | - You must check a condition before calling this method 9 | - You must call this method after setting properties 10 | - You cannot change this property after calling a method 11 | - This step must occur before that step 12 | 13 | These traps should not be documented; instead they should be refactored to be removed! 14 | *Otherwise the documentation will be a great case of Shameful Comment.* 15 | 16 | There are endless ways to make an API impossible to misuse: 17 | 18 | - Using types to only expose methods 19 | you can actually call, in any order 20 | - Using enums to enumerate every valid possible choice 21 | - Detecting invalid properties as early as possible (e.g. catching invalid inputs directly in the constructor) well before it is actually used then repair whenever possible, such as replacing nulls with null objects in the constructors or setters 22 | - It's not just about errors, but also about any harmful naive usage. For example if a class is likely to be used as the key in a hashmap, it should not make the hashmap slow or inconsistent. You could use internal caches to memoize the results of any slow computations of hashcode() and toString(). 23 | 24 | A common objection is that experienced developers don't get caught hence no need to be so defensive; however even good developers have more important things to focus on that avoiding the traps of your API. 25 | 26 | In the wording of Don Norman, these advises on how to guide the use of something would all be called "affordances", from his famous book "The Psychology of Everyday Things" (http://www.jnd.org/dn.mss/affordances_and.html) 27 | -------------------------------------------------------------------------------- /manuscript/NoDocumentation/NoDocumentation.txt: -------------------------------------------------------------------------------- 1 | '#NoDocumentation' is a manifesto for exploring alternatives to traditional forms of documentation. 2 | 3 | > We acknowledge the purpose of documentation, but we disagree with the way it's usually done. #NoDocumentation is about exploring better alternatives for transferring knowledge between people and across time. 4 | 5 | ![No Documentation!](images/nodocumentation.jpg) 6 | 7 | T> Documentation is only a mean, not an end. It's only a tool, not a product. 8 | 9 | Here are some ideas under the #NoDocumentation tag: 10 | 11 | - Conversations over Documentation 12 | - Continuous Training 13 | - All forms of collective work: Pair-Programming, Mob Programming, Specification Workshops, Communities of Practice 14 | - Declarative Automation 15 | - Shameful Documentation 16 | - Enforced Decisions 17 | - Make It Easy to Do the Right Thing 18 | - Making mistakes impossible 19 | - Scaffolding 20 | - On-demand Documentation 21 | - Throw-Away Documentation 22 | 23 | 24 | '#NoDocumentation': Make documentation redundant! 25 | 26 | > We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes. #agilemanifesto 27 | > -- @sgranese on Twitter 28 | -------------------------------------------------------------------------------- /manuscript/NoDocumentation/NotDeclarativeAutomation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/NotDeclarativeAutomation.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/ReadyMadeKnowledge.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/ReadyMadeKnowledge.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/Section------NoDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 8 No Documentation 2 | -------------------------------------------------------------------------------- /manuscript/NoDocumentation/ZeroDocumentation.txt: -------------------------------------------------------------------------------- 1 | # Zero documentation & Gamification 2 | 3 | 4 | **An approach to force better naming and better practice in general to share knowledge without additional prose** 5 | 6 | 7 | I've heard of a team who decided to forbid documentation: they're proudly doing Zero Documentation. And it isn't that stupid. 8 | 9 | Once you understand that most of the time written documentation prose or diagram is a poor substitute for expressing the knowledge better within the work product itself in the first place, it makes sense to minimize it. And because it sounds radical and a bit insane, it's stimulating and becomes a game. This makes it more likely to stick in team members mind, driving their behavior for the better, hopefully. 10 | 11 | I haven't tried it myself but what my colleague told me about it is that it's usually driving virtuous behavior in practice. 12 | 13 | Because we don't all share the same definition of the word "documentation", a game of Zero Documentation must clarify its rules. 14 | The above-mentioned team refuses comments in the code and on methods, all forms of written prose, external documents and traditional office documents. They happily embrace tests, Gherkin scenarios (Cucumber / Specflow), favor simple code, and enjoy working collectively as their primary mean of sharing knowledge. They're happy with all this. 15 | 16 | I think augmenting the code with annotations, a README file kept simple and generating living documents still fits within the rules of the game. You decide when to put the cursor! 17 | -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/ConversationsTraces.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/ConversationsTraces.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/EnforcedArchitecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/EnforcedArchitecture.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/decantation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/decantation.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/diagram_communication_modes_alistair_cockburn.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/diagram_communication_modes_alistair_cockburn.gif -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/diagram_communication_modes_alistair_cockburn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/diagram_communication_modes_alistair_cockburn.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/eclipse_pom_navigation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/eclipse_pom_navigation.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/fool.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/foyer.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/foyer.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/header-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/header-menu.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/nodocumentation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/nodocumentation.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/puppet-graph-complex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/puppet-graph-complex.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/sedimentation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/sedimentation.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/sonar_rules.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/sonar_rules.jpg -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/sonarreference.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/sonarreference.png -------------------------------------------------------------------------------- /manuscript/NoDocumentation/images/visible_hygiene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/NoDocumentation/images/visible_hygiene.png -------------------------------------------------------------------------------- /manuscript/README.txt: -------------------------------------------------------------------------------- 1 | Writing conventions in the manuscript folder 2 | 3 | # Structure 4 | 5 | Part 1 Reconsidering Documentation 6 | Part 2 Living Documentation exemplified by Behavior-Driven Development 7 | Part 3 Knowledge Exploitation & Augmentation 8 | Part 4 Automated Documentation 9 | Part 5 Runtime Documentation 10 | Part 6 Refactoring-Friendly Documentation 11 | Part 7 Stable Documentation 12 | Part 8 No Documentation 13 | Part 9 Beyond Documentation 14 | Part 10 Living Design & Architecture Documentation 15 | Part 11 Efficient Documentation 16 | Part 12 Introducing Living Documentation 17 | 18 | 19 | # Current state of the book 20 | 21 | - content is all there 22 | - content has yet to be reviewed and edited for better sentences 23 | - few pictures need cleaning or plain re-doing 24 | 25 | # Published content 26 | 27 | The magic file *book.txt* decides what goes into the published book. Only what's inside is actually published. The magic file *sample.txt* works the same way for the sample version of the book. 28 | 29 | # Work in progress 30 | 31 | Files in progress, not to be published as-is, have their name starting with '_', which is handy to have them sorted first in each folder, except the ones in the _attic, or in the _imported which will not be used anymore. 32 | 33 | # Images management 34 | 35 | - Because Leanpub expects every image to be in the single images/ folder, whereas Markdowm editors use regular relative links, I stored all images in a local images/ folder within each folder in the manuscript. Then I used a one line command line (update_images.command) to copy them all flat into the one official folder for Leanpub. It's far from perfect, but it works. 36 | 37 | - Images that are not in images/ folders are images to use later 38 | 39 | # TODO 40 | 41 | Files with TODO in the same mean these files are todo list in some aspect: 42 | 43 | - courtesy_TODO is all about asking permission to other authors to publish stuff they own 44 | - releasenotes_TODO is all about informing readers of the new content 45 | - humor_TODO is about including the WTF questions where appropriate to entertain a bit the reader; they should come with a funny drawing of a stupid boss, business analyst, developer or tester (à la troll face but novel) 46 | 47 | Files with lines starting with %% TODO also need some action 48 | 49 | ## Writing this book 50 | 51 | All the preparatory material and many sections of book have been written on the notepad of my iPhone 5, standing up in the Paris metro while commuting to and from customers. The majority of the actual writing was done on the Atom editor, on top of the excellent Leanpub + Github toolchain. 52 | 53 | 54 | Many pictures in this book were drawn by Yunshan Xia on 53 Paper with the 53 Pencil on Ipad Mini. 55 | -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/ModularDesign.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/ModularDesign.jpg -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/NamingAsPrimaryDocumentation.txt: -------------------------------------------------------------------------------- 1 | # Naming As The Primary Documentation 2 | 3 | *Searching for just the right words is a valuable use of time while designing.* 4 | 5 | (@KentBeck & @WardCunningham, http://t.co/PjQfDzRZcX) 6 | 7 | One of the most important tools is just naming. Despite its unattractiveness, naming should never be overlooked. More often than not, the names left by the original authors are the only element of documentation available to retrieve their knowledge. Good naming is extremely important. Good naming is immensely important. 8 | 9 | But good naming is hard. Names as social convention: need agreement and shared connotations. Thesaurus, conversations, active listening & overheard, names voting to the rescue! 10 | 11 | ## Naming: browsing a thesaurus 12 | 13 | Also good names are not just useful when reading them, they are also useful when you're searching for something. Good naming makes sure all names are searchable. For an example of naming that fails on the Search-able aspect, the programming language named "Go" is quite unlucky, especially considering that it originates from the "Search Company" known as Google. 14 | 15 | ## Composed methods, you need to name them. 16 | 17 | Names don't live in isolation. In object-oriented programming languages, the set of class names form a language, and the words have various relationships to each other, gaining expressivity as a whole. In the paper "A Laboratory For Teaching 18 | Object-Oriented Thinking" (1989), @KentBeck and @WardCunningham write: 19 | 20 | > The class name of an object creates a vocabulary for discussing a design. Indeed, many people have remarked that object design has more in common with language design than with procedural program design. We urge learners (and spend considerable time ourselves while designing) to find just the right set of words to describe our objects, a set that is internally consistent and evocative in the context of the larger design environment. 21 | 22 | For more on naming and practical advices, I suggest reading the chapter on naming written by Tim Ottinger in Robert C. Martin's book "Clean Code". 23 | -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/PlainTextWithTags.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/PlainTextWithTags.jpg -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/Section------RefactorableDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 6 Refactoring-Friendly Documentation 2 | -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/SourceControlReference.txt: -------------------------------------------------------------------------------- 1 | # Source Control is the Reference 2 | 3 | Source code has to be in source control. Period. What's the latest version of the code? It's easy, it's the code in the Mainline. 4 | 5 | For non source code there's more opportunity for ambiguity. Knowledge in text documents, slides or spreadsheets may be stored anywhere in many different places. "Where is the latest version of the project goals? - Mmmh, I don't remember, have a look in the shared drive, otherwise in the wiki or the intranet." 6 | 7 | We don't want to spend time chasing the latest decisions, or discussing what version of document to trust. No ambiguity requires simple rules. 8 | 9 | Therefore: **Any change should always be materialized as a commit.** 10 | 11 | No exception, or it would defeat the whole thing. Every piece of knowledge that is important for the project should be committed to the source control. Favor plain text documents whenever possible. 12 | 13 | When this pattern is not possible, a variant is to keep links to the right documents and to external repositories in the source control. To reduce link maintenance, consider using a Link Registry. 14 | 15 | In this ultimate approach, every changes requires a commit, with a commit comment. The commit can also trigger a build. The build can produce the latest version of all living documents, publish them where appropriate, send events to news feeds or company chat. 16 | -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/arrange_act_assert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/arrange_act_assert.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/command-event-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/command-event-diagram.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/composed_method_by_abstraction.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/composed_method_by_abstraction.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/diagrammr1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/diagrammr1.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/diagrammr2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/diagrammr2.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/dotdiagram_rendering.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/dotdiagram_rendering.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/matching_expressions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/matching_expressions.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/napkin_sketch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/napkin_sketch.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/table_code_layout.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/table_code_layout.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/type_signature_search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/type_signature_search.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/type_signature_search_int.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/type_signature_search_int.png -------------------------------------------------------------------------------- /manuscript/RefactorableDocumentation/images/uml_class_notation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/RefactorableDocumentation/images/uml_class_notation.png -------------------------------------------------------------------------------- /manuscript/Sample.txt: -------------------------------------------------------------------------------- 1 | frontmatter.txt 2 | 3 | Frontmatter/NoteToreviewers.txt 4 | 5 | Frontmatter/IntroductoryQuestions.txt 6 | Frontmatter/preface.txt 7 | Frontmatter/about.txt 8 | Frontmatter/credit.txt 9 | Frontmatter/HowToReadThisBook.txt 10 | 11 | mainmatter.txt 12 | 13 | 14 | Introduction/Section------Introduction.txt 15 | Introduction/ImagineTheIdealStory.txt 16 | Introduction/Problem.txt 17 | 18 | Introduction/AllAboutKnowledge.txt 19 | Introduction/KnowledgeOrigination.txt 20 | Introduction/NecessaryKnowledge.txt 21 | Introduction/PeterNaurTheoryPassing.txt 22 | Introduction/KnowledgeTransfer.txt 23 | Introduction/SpecificVsGeneric.txt 24 | Introduction/KnowledgeIsAlreadyThere.txt 25 | 26 | Introduction_Overview/ExternalInternalDocumentation.txt 27 | Introduction_Overview/AccuracyMechanism.txt 28 | 29 | Introduction/Checklist.txt 30 | Introduction/DocumentationReboot.txt 31 | Introduction/GatewayToDDD.txt 32 | 33 | Introduction_Overview/SpineModel.txt 34 | Introduction/Fun.txt 35 | 36 | bdd/Section------LivingDocumentationBDDExample.txt 37 | bdd/BDD.txt 38 | bdd/RichDomainDescription.txt 39 | 40 | 41 | 42 | 43 | LivingDocumentation/Section------LivingDocumentation.txt 44 | LivingDocumentation/LivingGlossary.txt 45 | LivingDocumentation/BusinessDomainDiagram.txt 46 | 47 | 48 | 49 | NoDocumentation/Section------NoDocumentation.txt 50 | NoDocumentation/NoDocumentation.txt 51 | 52 | BeyondDocumentation/Section------BeyondDocumentation.txt 53 | BeyondDocumentation/HygienicTransparency.txt 54 | 55 | 56 | 57 | backmatter.txt 58 | -------------------------------------------------------------------------------- /manuscript/StableDocumentation/AcknowledgedInfluences.txt: -------------------------------------------------------------------------------- 1 | # Acknowledge your influences 2 | 3 | ## Project Bibliography 4 | 5 | Good books care about their bibliography. For the reader, it's a way to learn more, but it's also a way to check the influences of the author. When a word has different meanings, looking at the bibliography helps find out how to interpret it. 6 | 7 | > Read the Book! -- Eric Evans, in Domain-Driven Design 8 | 9 | A project bibliography provides a context for the readers. It reveals the influences of the team at the time of building the software. 10 | 11 | The project bibliography is composed of links to books, articles and blogs either crafted by hand or extracted from your annotations and comments, or using a mix of both. 12 | 13 | ## Declare your Style 14 | 15 | Like painters that belong to specific painting schools like the Surrealists or the Cubists, there are various schools of thoughts in software development. 16 | 17 | Some painters can switch between styles from one work to another; similarly, developers can create a module in a very functional-programming style, with everything pure and immutable, and another using semantic technologies and graph-oriented stores. 18 | 19 | To provide context for the readers, it is useful to declare the style and the main paradigm if any that you chose for some area of code, typically for a module or for one project. 20 | 21 | This overall statement show some similarity to a resume, but for the team or teams: 22 | - Modeling Paradigms (DDD) 23 | - Authors we follow 24 | - Books we've read, blogs we often go to 25 | - Languages and frameworks we're familiar with 26 | - Any kind of inspiration that matters, e.g. "Stripe as an inspiration for developer-friendliness" 27 | - Typical kinds of projects we've mostly done so far (web, server, embedded, crud...) 28 | 29 | To be refactoring-proof, this information should reside within the module or project itself. It can be done with annotations @Style(Styles.FP) on packages (Java), attributes on the AssemblyInfo (.Net) or using a style.txt file with a key-value syntax at the root of the module or project. 30 | 31 | A> Style is also useful for tools; for example the declared style can be linked to specific rulesets for static analysis. 32 | 33 | Declaring your style also helps enforce consistency within area of the code base. 34 | 35 | A> ![LOL](images/fool.png) 36 | A> 37 | A> Coined Gierke's law yesterday: from the structure of a software system you can derive the book the architect read most recently... 38 | A> From Oliver Gierke [@olivergierke](https://twitter.com/olivergierke) on Twitter 39 | -------------------------------------------------------------------------------- /manuscript/StableDocumentation/Section------StableDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 7 Stable Documentation 2 | -------------------------------------------------------------------------------- /manuscript/StableDocumentation/StrategyImplementationSeparation.txt: -------------------------------------------------------------------------------- 1 | # Don't Mix Strategy Documentation with the documentation of its implementation 2 | 3 | *Strategy and its implementation don't evolve at the same pace* 4 | 5 | In the page 80 of their book "Agile Testing: A Practical Guide for Testers and Agile Teams Book", Lisa Crispin and Janet Gregory recommend not to mix the documentation of a strategy with the documentation of its implementation, taking the example of the test strategy: 6 | 7 | > If your organization wants documentation about your overall test approach to projects, consider taking this information and putting it in a static document that doesn't change much over time. There is a lot of information that is not project specific and can be extracted into a Test Strategy or Test Approach document. 8 | > 9 | > This document can then be used as a reference and needs to be updated only if processes change. A test strategy document can be used to give new employees a high-level understanding of how your test processes work. 10 | > 11 | > I have had success with this approach at several organizations. Processes that were common to all projects were captured into one document. Using this format answered most compliance requirements. Some of the topics that were covered were: 12 | > 13 | > - Testing Practices 14 | > - Story Testing 15 | > - Solution Verification Testing 16 | > - User Acceptance Testing 17 | > - Exploratory Testing 18 | > - Load and Performance Testing 19 | > - Test Automation 20 | > - Test Results 21 | > - Defect Tracking Process 22 | > - Test Tools 23 | > - Test Environments 24 | 25 | Therefore: **Don't mix documentation of a strategy and documentation of its implementation. Make the strategy documentation a pure Evergreen Document. Use another Living Documentation approach for the implementation, considering the implementation will change more frequently.** 26 | 27 | The strategy should be documented as an Evergreen Document, stable and even shared between multiple projects. Omit every detail that could change or that would be project-specific from the strategy document. All theses details that change more frequently and that differ from project to project must be kept separately, probably using the techniques proposed in this book which are more suited for knowledge that changes often: declarative automation, BDD etc. 28 | -------------------------------------------------------------------------------- /manuscript/StableDocumentation/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/StableDocumentation/images/fool.png -------------------------------------------------------------------------------- /manuscript/StableDocumentation/images/napkin_sketch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/StableDocumentation/images/napkin_sketch.png -------------------------------------------------------------------------------- /manuscript/VisibleWorkings/Interpreter.txt: -------------------------------------------------------------------------------- 1 | 2 | ## Interpreter 3 | 4 | From the perspective of a living documentation, this approach is like cheating. Instead of having to document how the code is doing a processing, let the description of how to do the processing drive the code literally. 5 | 6 | **Write the formula or processing description as a "script" using a convenient syntax of your choice. This may be a custom syntax, a DSL or another programming language. Make sure this description is as easy to read as possible, especially for non-developers. Then write code that simply interprets this description to perform its job. This interpreter code should have as little calculation knowledge as possible, because the point is to have all this knowledge in the script. Make sure to make the scripts accesible at runtime in an easy way.** 7 | 8 | Examples: using Lua, Javascript, BPMN and other declarative workflow syntaxes, custom Structurer Syntax etc. 9 | 10 | This approach is common in many large software systems from vendors, because they need a lot of flexibility to accomodate the varying needs of each customer. If this approach is pushed to far, the result is that the application becomes a kind of SDK in which many developments are done in the specific syntax. This means work has to be done in a rather poor development environment: no unit-testing, no autocompletion, no syntax highlighting, no compile-time checks, no debugger etc. However the Interpreter approach works very well when used reasonably. 11 | 12 | This is Single Source of Truth at its finest. 13 | -------------------------------------------------------------------------------- /manuscript/VisibleWorkings/Section------RuntimeDocumentation.txt: -------------------------------------------------------------------------------- 1 | -# Part 5 Runtime Documentation 2 | -------------------------------------------------------------------------------- /manuscript/VisibleWorkings/VisibleWorkings.txt: -------------------------------------------------------------------------------- 1 | # Visible Workings: Working Software as its own Documentation 2 | 3 | ## Working software as documentation 4 | 5 | The Agile Manifesto says "Working Software over Comprehensive Documentation". What if the working software was itself a kind of documentation? 6 | 7 | It is already quite common to design the User Experience so that the users can have successful interactions with an application without ever having to open the user manual. However, it's less common to design the software so that its developers can understand it without even having to open the source code. 8 | 9 | It is possible to learn the business domain to some extent just by using a related and well-designed application. The software is by itself a piece of documentation about itself and its business domain. This is why every developer on an application should at least know how to use their application for most standard use-cases, even if it is a complicated application dealing with complicated financial instruments. 10 | 11 | T> Anything that can answer a question can be considered documentation. If you can answer questions by using the application, then the application is part of the documentation. 12 | 13 | ## Visible Workings 14 | 15 | A more radical perspective on the software as a documentation is to rely on the software itself to explain how it works inside, something Brian Marick calls **Visible Workings**, i.e. make the internal mechanisms visible from the outside. 16 | 17 | There are many ways to achieve that, and they all have in common to rely on the software itself to output the desired form of documentation. 18 | 19 | As an example, many application perform calculations like payrolls or bank statements and other forms of data crunching. It is often necessary to describe how the processing is done, for external audiences like business people or compliance auditors. 20 | 21 | You may think of Visible Workings approaches like an 'export' or 'reporting' feature, but on the way it works internally. You want to be able to ask the software "How do you compute that?" or "What's the formula for this result?", and it just tells you, at runtime. There should be no need to ask a developer to get the answer. 22 | 23 | It's the kind of feature that is not often requested by the customer, but it's a valid answer to a need for more documentation. It's also worth noting that the development team has full latitude to decide to add features that make its own life easier, since the team is obviously one of the key stakeholders of any project. The key is to spend just enough time for the expected benefit. Visible Workings techniques are obviously very useful for the development teams. 24 | 25 | This pattern comes in various forms: 26 | 27 | - Introspectable Workings 28 | - Visible Calculation 29 | - Queryable Object Log 30 | -------------------------------------------------------------------------------- /manuscript/VisibleWorkings/images/introspectable-generated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/VisibleWorkings/images/introspectable-generated.png -------------------------------------------------------------------------------- /manuscript/VisibleWorkings/images/introspectable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/VisibleWorkings/images/introspectable.png -------------------------------------------------------------------------------- /manuscript/VisibleWorkings/images/introspecting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/VisibleWorkings/images/introspecting.png -------------------------------------------------------------------------------- /manuscript/_AlternativeTitles.txt: -------------------------------------------------------------------------------- 1 | ## Alternate titles: 2 | 3 | - Transparent Design 4 | - Deliberate Design 5 | - Exposed Design 6 | - Published Design 7 | - Literate Design 8 | - Decision-Revealing Design 9 | - Continuous Documentation 10 | - Continuous Design 11 | - Living Documentation / Reliable documentation for free with Domain-Driven Design 12 | - Comprehensive Documentation lol 13 | 14 | (Litmus test: the fundamentals of LD should work with all these titles) 15 | -------------------------------------------------------------------------------- /manuscript/_TheProcessOfWritingThisBook.txt: -------------------------------------------------------------------------------- 1 | How I wrote the book, and what I learnt in the process 2 | 3 | This is my first book, so I learnt a lot during the process. 4 | 5 | - Dump the content ASAP 6 | - Organize later, when the content is there and you can see it 7 | - Annotate the content so that it can be searched, and to identify clusters of related ideas 8 | - Manage your motivation: watch the word and page count; meet the audience early 9 | - Keep the topic in mind all the time, so that serendipity operates; new ideas, examples and related quotes will come to you every day 10 | - I decided to write a lot of mostly independent small chapters, grouped ini folders. This modularity had helped seeing the outline in the navigation pane of my text editor 11 | - An automated publishing factory like Leanpub is very useful. Having everything in plain text and plain images is simple. I tried other tools and settled on the simplest chain. 12 | - Keep a companion *release notes* file, and a companion *courtesy* file with every question and asking permission to other people about their content. I should also keep an *index* file to grow along the road to define the index outline 13 | - I've been using the built-in iOS Notes application and its Mac OS counterpart. With that combo I've been able to write a lot of early drafts of chapters on my iPhone, before editing them on the laptop later. 14 | - Use naming conventions or tags to categorize your material for later use. I relied on a naming convention prefix "LD - " to do the curation of all the notes related to the book, excluding the other unrelated notes. I used the same convention in my emails when capturing notes, quotes and useful links anywhere. 15 | - Because Leanpub expects every image to be in the single images/ folder, whereas Markdowm editors use regular relative links, I stored all images in a local images/ folder within each folder in the manuscript. Then I used a one line command line (update_images.command) to copy them all flat into the one official folder for Leanpub. It's far from perfect, but it works. 16 | -------------------------------------------------------------------------------- /manuscript/_attic/_CaseStudy_DesigningTags.txt: -------------------------------------------------------------------------------- 1 | # Case Study: Designing a system of annotations 2 | 3 | ## A matter of coverage 4 | 5 | Scope (see commit comments, business rules @wip, @Billing, @policy) 6 | -------------------------------------------------------------------------------- /manuscript/_attic/_CodeReadingAndProjectDiscovery.txt: -------------------------------------------------------------------------------- 1 | 2 | Assertion in code are documentation of your assumptions 3 | 4 | @tottinge: Code is documentation. Period. Bad, clumsy, ugly code is just really lousy documentation. 5 | 6 | -- 7 | Thread macro clojure, F# |> to document visually 8 | 9 | -- 10 | 11 | Code is not literature. Code is not enough. No way you can save the effort from learning the domain, the code is just its materialization. 12 | 13 | ### abstract/generic vs domain-meaningful & potential vs actual 14 | Worst: for many reasons we chose to reduce duplication and that leads to more abstraction. 15 | 16 | Example in Clojure from Gilles Ph. 17 | Fetch-all 18 | Fetch from repository = Fetch-all (repository) 19 | Fetch from users = Fetch-all (user) 20 | 21 | When we do that, the code tends to becomes mostly abstract & domain-agnostic, except when we instantiate the generic bits to tell the domain story. 22 | 23 | Example of JScience doing matrix calculations on plain math structures. (Generic sub-domains) 24 | 25 | Well-factored code tends toward building blocks that can be composed in many combinations. For each combination, some of the building blocks are often not used. The set of all building blocks forms a toolkit. This is the set of all bits add piece you may need in some situation, but not always. 26 | 27 | If your code has building blocks, then the documentation should simply describe it as such. But because each block in itself is not much useful, you also need to provide a gallery of concrete useful examples that use the building blocks. 28 | 29 | These examples will be like tests, except they don't have to assert anything except that they compile successfully. These examples may be organized by task, e.g. "How to solve this problem". 30 | -------------------------------------------------------------------------------- /manuscript/_attic/_DocumentationByAnnotations.txt: -------------------------------------------------------------------------------- 1 | %% TODO add to documentation by annotation (for design) 2 | 3 | 4 | --- 5 | 6 | When an association is keyed, we use a Map or Dictionary or Hashtable. When the member field is well-named and the key and value have well-named types, then there is often nothing more to tell. When a type is not specific enough, we may have to resort to add a declaration: 7 | 8 | @KeyedBy("Buy-Side Counterparty") 9 | private final Map exposure; 10 | 11 | Why an annotation? Well, you could just go with a regular comment: 12 | 13 | // KeyedBy Buy-Side Counterparty 14 | private final Map exposure; 15 | 16 | However the annotation can be used by tools to recognize 17 | 18 | --- 19 | 20 | patterns help in documenting code. As a developer I often spend 21 | (too) much time to write good Javadoc documentation; if I were offered some 22 | more pattern tags I will be able to describe my intention with words, not sentences: 23 | I will save time again. 24 | 25 | ## How does it map to the core principles? 26 | 27 | Low-effort: 28 | Easy to add to a class, method or even package 29 | A unique location to describe a brief explanation along with links to further complete references 30 | IDE "Find Usages" to find every occurrence, for on-demand documentation (instead of making it a document) 31 | 32 | 33 | Collaborative: 34 | The annotation is just a bookmark for a thinking that happened through pair-programming or all-team on the whiteboard discussion 35 | To train "on-the-spot" the colleagues who are going to maintain it 36 | 37 | Reflective / Insightful: 38 | If it's hard to annotate what you're doing it means you don't know what you're doing well enough. Ask for help to colleagues or grab a book on the topic. 39 | When annotations drive the generation of a reporting document, e.g. a design diagram, this document provides feedback and insights. For example you may discover unexpected coupling and many other surprises. 40 | 41 | Of course everybody also uses annotations to implement behavior like transaction demarcation and configuration of frameworks. Please don't get confused between annotations that implement behavior and annotations that are solely meant to transfer knowledge from the authors of the code to their successors. 42 | -------------------------------------------------------------------------------- /manuscript/_attic/_DocumentationLandscape.txt: -------------------------------------------------------------------------------- 1 | # Documentation Landscape (Andrea Ruping) 2 | 3 | 4 | # Add tags the way you would look for it - task-oriented indexing? 5 | 6 | Meta annotation to find everything documentation everywhere without any entry point. Full-text search for the string "documentation" in the core base and find out everything of interest. 7 | 8 | --- 9 | 10 | -- 11 | @Policy to produce a report of the most important business policies from the code, and where to audit them. 12 | 13 | --- 14 | 15 | 16 | ## Different kinds of content 17 | - Content Ordering: narrative, logical, dramatic 18 | - Decision / Task Oriented 19 | - Intention Revealing 20 | 21 | 22 | ## Segregate asset vs temporary information 23 | 24 | Sprint vs System/product 25 | %% insert picture 18/12/2013 26 | 27 | 28 | 29 | ## Project Overview 30 | 31 | Let's assume that we have a project with source code well organized into packages, layers etc. Its Vision Statement, the Bounded Contexts and their Ubiquitous Language are stored as text files at the root of the project. The relationships between contexts and the possible Anti-corruption layers used could also be described there. 32 | 33 | During development many of the programming language elements (interfaces, classes, methods, packages) have been annotated with patterns annotations to declare every pattern (DDD, GoF, Fowler Analysis and PoEAA patterns in particular) that we know are present at the design and architecture levels. 34 | 35 | Even the frameworks used may have been also declared using the pattern vocabulary. For example the ORM would be declared as being a Data Mapper. 36 | -------------------------------------------------------------------------------- /manuscript/_attic/_DocumentationMigration_BRIEF.txt: -------------------------------------------------------------------------------- 1 | Guidebook: a mix of evergreen and living documents covering the big picture: persona, vision, stakes (text or slides), Quality Attributes (code as a DSL), brief glossary, a few key scenarios, external actors in a context diagram, principles (annotations with rationale), technologies & dependencies (comments in Pom manifest) 2 | 3 | 4 | 5 | ### TO ADD TO ARCHITECTURE SECTION 6 | 7 | @abdullin: Started developing a new module, using auto-generated diagram as first development feedback. Fast feedback FTW! http://t.co/PU0puXN2L3 8 | 9 | To illustrate that, I would say that I decided to write this book to share about Living Documentation because: 10 | - I love to code 11 | - I hate doing the same thing twice 12 | - I have documentation but I acknowledge there's a need to be fulfilled 13 | - I tried many ideas to fix that, and many of them made my life easier, so now I'm hooked and would like other to be hooked too. 14 | 15 | 16 | ## Enforced Architecture 17 | 18 | Architecture is a lot about self-imposed constraints: 19 | restricted dependencies 20 | segregation of elements by chosen criteria 21 | hygiene rules and guidelines 22 | chosen architectural styles... 23 | 24 | You can spend time documenting all that in guide books and prescriptive documents. Or you can try to enforce them automatically. For example during the builds you can verify that the code satisfies the hexagonal architecture, using tests or assertions at runtime. 25 | 26 | It's interesting to notice that this is often only possible provided that your code is well-annotated. 27 | 28 | 29 | --- 30 | ## Semantics from the use / proximity with other concepts (Mathieu Pauly) 31 | 32 | ----- 33 | -------------------------------------------------------------------------------- /manuscript/_attic/_DocumentationStrategy.txt: -------------------------------------------------------------------------------- 1 | # Defining a Documentation Strategy 2 | 3 | 4 | 5 | ## When LD is not the right fit 6 | 7 | - Goals? why? Risk-Adjusted or Benefit-Adjusted: A matter of retrospective 8 | - Let the team decide how to implement, 9 | -------------------------------------------------------------------------------- /manuscript/_attic/_ImplementationPrinciples.txt: -------------------------------------------------------------------------------- 1 | # Implementation Principles in a nutshell 2 | 3 | * **Reliable** 4 | - Single source of truth (code, tests, runtime...) 5 | - Reconciliation mechanism (tests, validations) 6 | 7 | * **Low-Effort** 8 | - Simplicity (nothing to declare) 9 | - No documentation (avoiding the need for documentation: standard etc) 10 | - Perennial knowledge (stuff that does not change) 11 | - Refactorable knowledge (stuff that can change automatically) 12 | - Intrinsic knowledge + collocated (stuff that to together) 13 | 14 | 15 | * **Collaborative** 16 | - Conversations over documentation 17 | - Knowledge decantation 18 | - Accessible knowledge (make accessible to all audiences) 19 | - Collective ownership (developers don't own the documentation, they just own the technical responsibility) 20 | 21 | * **Insightful** 22 | - Deliberate design (do I know what I'm doing? + tooling can help change behaviors) 23 | - Embedded learning 24 | - Emotional feedback (feedback with a sense of good or bad) 25 | 26 | 27 | -- 28 | Anecdote de Claude Falguière 29 | > Specs écrites, mais incompréhensibles. Les devs suggèrent de faire des revues des specs, les analystes décident de faire d'abord des revues entre eux. La semaine suivante, au reporting : "les revues on les a pas faites, car on n'arrive pas à relire et comprendre les specs" lol 30 | -------------------------------------------------------------------------------- /manuscript/_attic/_InterviewHeuristics.txt: -------------------------------------------------------------------------------- 1 | # Modeling questions heuristics 2 | 3 | ## Before 4 | 5 | - Do your homework: read about the topics, books, Google search, Wikipedia, investopedia, XML standards of the field. 6 | - Know your patterns: design, DDD, analysis 7 | - Train in various modeling techniques: CRC Cards, UML in Color, Event Storming etc. 8 | 9 | ## During interview 10 | 11 | - Always ask **"WHY?"** (several times if needed) 12 | - Ask **"FOR WHO?"** Identify stakeholders: "Who decides that?" "Who would disagree with that?" 13 | - Note the exact words, **verbatim**. 14 | - Don't interrupt the business people, **write down your questions** to ask them minutes later. 15 | - While listening, **scan your notes** to find your next questions. 16 | - On your notes, **mark each word mentioned for the first time**. 17 | - Ask for the definition of each new words: **"How would you define X?"**. 18 | - Ask often **"Gimme an example please!"** (you can't abuse this question). 19 | - Challenge respectfully the domain experts: they may not always be right, they may even be wrong or lack perspective. Don't tell them they're wrong though. 20 | - Pay attention to **side remarks**, and note them. They may reveal the hidden side of the iceberg. 21 | - **Pay attention to hesitations and unconvincing answers**. 22 | - Ask for clarification whenever it seems that **different words** are used indifferently: this may suggest distinct Bounded Contexts. 23 | - Challenge internal consistency: confront two previous **statements that could contradict** with each other. 24 | - Look for **invariants** (properties that should be always true). 25 | - Challenge invariants, even obvious ones: **"in what conditions this would not be alway true?"**.. 26 | - Ignore technology: How was this done before we had computers? 27 | - If you already suspect the relevance of a **known pattern** (e.g. Analysis Patterns), ask domain questions to know better.. 28 | 29 | ## After 30 | 31 | - Immediately code what you understood 32 | - Note every question, hesitation, contradiction for the next interview 33 | 34 | **Iterate** 35 | -------------------------------------------------------------------------------- /manuscript/_attic/_LayeredDotNet.txt: -------------------------------------------------------------------------------- 1 | ## Layered app in .Net 2 | 3 | A typical architecture for .Net applications is the [Layered Application](https://msdn.microsoft.com/en-us/library/ee658109.aspx#Step4) 4 | 5 | The key to Layered Application is dependency management. Components in one layer can interact only with peers in the same level or components from lower levels, as in [Frank Buschmann](Pattern-Oriented Software Architecture, Patterns for Concurrent and Networked Objects, Volume 2). This helps bring some structure and reduce the dependencies between components on different levels. Layering can be strict: dependencies only allowed to the layer directly below) or relaxed: dependencies allowed to any layer below. 6 | 7 | Depending on the age of your application, you would have gone for a 3 layers architecture: presentation, business and data, or you would go for a 4 layers architecture today: presentation, services, business, data. Note that the layers can be collapsed in case one is almost empty. 8 | 9 | The presentation layer contains everything UI for smart client interaction or browser-based interaction. The business layer is all about functionalities, workflow, calculations and representing the business domain. The data layer provides access to external systems such as databases, mainframes or external web-services. 10 | 11 | By convention in .Net, the layered are represented by sub-projects and namespaces. 12 | -------------------------------------------------------------------------------- /manuscript/_attic/_LiterateProgramming.txt: -------------------------------------------------------------------------------- 1 | ## Literate programming 2 | 3 | # Literate Programming 4 | 5 | 6 | F#, Clojure, Python 7 | Standard F# file, with embedded Markdown narrative special comments in linear reading order. The comments may decide to skip a section of code, and may decide to include code from another place on request. This way you control when you introduce a piece of code in your narrative. The default ordering is just the linear ordering of dependencies in F#, enforced by this language. 8 | 9 | For example you can create a "Getting Started" page, with narrative text and code snippets, both collocated within the same standard F# file. 10 | 11 | In the generated report, the code has tooltips, when you hover over it you can see the type information. And when you click on code identifiers, they become links towards the source code on a repository like GitHub. 12 | 13 | [Marginalia](https://github.com/gdeer81/marginalia) 14 | 15 | Groovy Spock test framework extracts the expression from the code in its failing tests reports 16 | 17 | 18 | Dexy: like make but for documents 19 | - Place prose in the code 20 | - Place code in the prose 21 | - Code is code, prose is prose, with tools to mix them together, plus data! 22 | 23 | Code, prose and data cost money. On the other hand, analysis, documentation and reporting have value 24 | 25 | 26 | literate programming is not a way to do documentation but a way to write programs 27 | -------------------------------------------------------------------------------- /manuscript/_attic/_Minimum_Readme.txt: -------------------------------------------------------------------------------- 1 | Minimum Viable Documentation, README 2 | 3 | 4 | 5 | 6 | > Aim to write the Minimum Viable Documentation. The rest is waste. 7 | >@PeterHilton 8 | 9 | 10 | 11 | 18F logo 18F Open Source Style Guide "Making READMEs readable" 12 | 13 | https://pages.18f.gov/open-source-guide/making-readmes-readable 14 | 15 | > Every repo contains a README, which is a document that is intended to explain, at first glance, what a project does and how to install or test the code. 16 | -------------------------------------------------------------------------------- /manuscript/_attic/_More_TypeDrivenDocumentation.txt: -------------------------------------------------------------------------------- 1 | ALREADY INCORPORATED 2 | 3 | See studies: "Types names help more than documentation" 4 | 5 | http://www.slideshare.net/mobile/devnology/what-do-we-really-know-about-the-differences-between-static-and-dynamic-types 6 | 7 | Comments can lie and they often do. So does naming, to a less extent. But types don't lie, or the program would not even compile. 8 | 9 | A method name may pretend to be: 10 | 11 | GetCustomerByCity() 12 | 13 | But regardless of its name, if the signature and its types is actually: 14 | 15 | List f(ZipCode) 16 | 17 | You get a much more accurate picture of it really is. And it could even be improved: List could be a type in itself, something like Prospects or ProspectionPortfolio. 18 | 19 | if it was Set we would know that a prospect can only be present once. 20 | 21 | 22 | Types are more accurate than naming and comments. 23 | 24 | **Therefore: Use types whenever possible, the stronger the better. Avoid bare primitives and bare collections. Promote them into first-class types. These types are named hence they are a support for communicating the Ubiquitous Language. Favor types over free comments, but don't neglect to describe the types in their structured comments.** 25 | 26 | With just primitives you're in your own to decide if you can trust the naming or not. What does the Boolean "ignoreOrFail" mean? Enums add accuracy: IGNORE, FAIL 27 | 28 | Optional expresses the possible absence of result with total accuracy. In languages that support them, monads signal the presence of side-effects with total accuracy. In these examples the information is accurate because the compiler enforces it. 29 | 30 | Generics: Map tells a lot, whatever the variable name. 31 | -------------------------------------------------------------------------------- /manuscript/_attic/_QueryableObjectLog.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_attic/_QueryableObjectLog.txt -------------------------------------------------------------------------------- /manuscript/_attic/_SkillsMatrix.txt: -------------------------------------------------------------------------------- 1 | # Skills Matrix (automated from source control? Declarative?) 2 | 3 | From [Jim Heidema](http://www.agileadvice.com/2013/06/18/agilemanagement/leaving-your-title-at-the-scrum-team-room-door-and-pick-up-new-skills/) 4 | 5 | This is a chart that can be posted in the room to identify the skills needed and the people on the team. On the left column you list all the team members. Along the top you list all the various skills you need on the team. Then each person reviews their row, looking at each skill, and then identifies how many quadrants of each circle they can fill in, based on the range below the chart. The range is from no skills through to teach all skills in a given column. After filling the columns and rows, now the work begins. 6 | 7 | By using pair programming (an extreme programming method) and other methods like self-study and taking additional courses, the team member can begin to learn other skills. The objective is to have at least two persons on each team who possess each of the skills at the level of performing all the tasks of a specific skill. The goal is not to have every one do everything but to have a least enough people with specific skills to cover sicknesses and vacations so that required tasks are performed. This is a method to capture the full extend of each person's current knowledge, skills and abilities and expand on it. 8 | -------------------------------------------------------------------------------- /manuscript/_attic/_TransparentConfiguration.txt: -------------------------------------------------------------------------------- 1 | # Transparent Configuration 2 | 3 | ## Spreadsheet-Driven 4 | 5 | Excel as a golden source 6 | 7 | Import the data from the Excel spreadsheet (or API import from Google Doc) and keep a copy of the spreadsheet too as a blob; its comments, headers and overall layout are (or should be) meaningful. 8 | 9 | In a previous project we started with nothing in database and all the configuration directly in Excel spreadsheets stored as resources. Even if the business people could modify them, they had to ask developers to commit them. These spreadsheets were considered part of the source code and put in version control along with the code. 10 | 11 | On startup (or on-demand through an admin button), all the spreadsheets were loaded into memory for every session to use. 12 | 13 | When someone wanted to know about the specification, developers just had to hand the set of spreadsheets, as a zip archive or as a link to the source control. The spreadsheet used colors, comments and formatting to help explain what was going on. 14 | 15 | Masks at Sungard as .xls edited by product managers with colors, remarks etc. 16 | 17 | Todo interview Nicolas Romaneti executable specs google doc spreadsheet as documentation / specs 18 | 19 | Project Gageot, De Morlhon, Romanneti et Ramiere with all business rules in Google Doc 20 | -- 21 | -------------------------------------------------------------------------------- /manuscript/_attic/_blogs_etc.txt: -------------------------------------------------------------------------------- 1 | On blogs 2 | 3 | Some Past facts with a very visible date are eternal. For example a blog lists posts, each with its date. Each blog describes something, that may be decisions or a state of the system that was true at its publication date. However, even if the decision or state of the system have changed since, the blog post remains relevant because each post clearly shows its date. Also a blog post typically describes a mood, a thinking, a decision or an observation of the moment. This is in contrast with typical documentation that promises much more, and too much indeed. 4 | 5 | 6 | # Decision Log / Evergreen / Blog 7 | 8 | Today I Learned (TIL) Short independent articles that each document one thing. Markdown files in a GitHub repository in ``/til/`` 9 | -------------------------------------------------------------------------------- /manuscript/_attic/_legacy_doc_ideas.txt: -------------------------------------------------------------------------------- 1 | LD - Documenting Legacy 2 | 3 | 4 | 5 | ---------- 6 | 7 | @KevlinHenney: The universe is made of information, but it doesn't have meaning — meaning is our creation. Searches for meaning are ∴ searches in a mirror. 8 | 9 | == lack of structure == 10 | The biggest issue in legacy code is the big gap between the structure we would expect, clear and relatively simple, and the actual state of the code as a big confused mess. 11 | 12 | (Example: football team 13 | Code randomly mixes sorting of players by name 14 | Your mental expectation is to sort them by role or scoring) 15 | 16 | Example: code modules by DAO, DTO, Controller... Vs. Billing, Recommendation, Shopping Cart, Catalog. 17 | 18 | The mapping between both structures is just a set of a huge number of arbitrary one-to-one relationship. 19 | 20 | You can add intrinsic information where they belong: this DTO is part of the billing, this one is part of the Catalog, etc. 21 | 22 | This will help prepare the next step: move the classes that deal with Billing into the same Billing module. But even if you don't, your code now has an explicit structure by business domain. 23 | 24 | == When you have to do it the soft way == 25 | 26 | It is hard to touch and commit large code bases just to add extra annotations. You don't want to risk introduce random regressions. You don't want to touch commit history. It may be so hard to build that you don't want to build it unless absolutely necessary. Or your boss may refuse you change the code at all "just for documentation". 27 | 28 | If it is possible then that's the best way, according to the intrinsic principle. 29 | 30 | Otherwise we can do a proof of concept at smaller scale using external annotations combined with parsing the actual source. 31 | 32 | -- 33 | -------------------------------------------------------------------------------- /manuscript/_attic/_listen_to_doc.txt: -------------------------------------------------------------------------------- 1 | Listen to your documentation! 2 | 3 | If it's hard to extract your living glossary or living diagrams out of your code, then what does that difficulty is telling you? 4 | 5 | Perhaps you were expecting some design structure, but when trying to render it as a diagram you have to admit the code does not exhibit much structure after all. You were expecting the code to tell the business domain, but when trying to make it into a glossary it appears that the business is mangled in the middle of the processing and there is no easy way to get it out. 6 | 7 | Steeve Freeman and Nat Pryce said in the GOOS book: "listen to your tests". if it's hard to test then probably your code is not well designed, and you should fix that. 8 | 9 | The same advice applies to documentation: if it's hard to extract a living documentation out of your code, then your code probably has problems, and you should investigate how to fix that. 10 | -------------------------------------------------------------------------------- /manuscript/_attic/_quotesPeterHilton.txt: -------------------------------------------------------------------------------- 1 | Peter Hilton From Documentation Avoidance slides 2 | 3 | [Peter Hilton on Documentation Avoidance](https://www.slideshare.net/pirhilton/documentation-avoidance) 4 | 5 | 6 | 7 | 8 | --- 9 | -------------------------------------------------------------------------------- /manuscript/_attic/_quotes_PragProg.txt: -------------------------------------------------------------------------------- 1 | Tip 68 2 | "Build Documentation In, Don't Bolt It On" 3 | 4 | "In general, comments should discuss why something is done, its purpose and its goal. The code already shows how it is done, so commenting on this is redundant—and is a violation of the DRY principle." 5 | 6 | What we don't want: 7 | Misleading names 8 | Hungarian notation 9 | Revision history -> source control 10 | List of files this file uses -> parser or dependency manifest 11 | -------------------------------------------------------------------------------- /manuscript/_attic/_theoryBuilding.txt: -------------------------------------------------------------------------------- 1 | Peter Naur - Programming as Theory Building 2 | 3 | as introduced by REMZI H. ARPACI-DUSSEAU in pages.cs.wisc.edu/~remzi/Naur.pdf 4 | 5 | > The quality of the designer's work is is related to the match between his theory of the problem and theory of the solution. Note that the quality of a later programmer's work is related to the match between his theories and the previous programmer's theories. 6 | 7 | > Using Naur's ideas, the designer's job is not to pass along "the design" but to pass along "the theories" driving the design. The later goal is more useful and more appropriate. It also highlights that knowledge of the theory is tacit in the owning, and so passing along the theory requires passing along both explicit and tacit knowledge. 8 | 9 | 10 | (Peter Naur, Programming as Theory Building, 1985) 11 | 12 | The key aspect of programming "is to have the programmers build a theory of the way the matters at hand may be supported by the execution of a program." 13 | 14 | 15 | -- 16 | 17 | - Interactive: tweakable tests, Visible Workings, Small-Scale Models 18 | - Redundancy of media: Source Code, Integrated Documentation in IDE, generated living Diagrams, Domain-Specific sketches (Smoke & Mirror, Ruth Malan?) 19 | - Background: influences from the literature, dominant styles of code, design and architecture 20 | - Recorded decisions and their Rationales 21 | - Metaphors 22 | - Tribal knowledge by Working Collectively with veterans of the system 23 | 24 | -- 25 | Project = Delivery + Learning 26 | 27 | - Keep it all versioned together 28 | - Keep track of what's been learnt and understood. What's has been preferred, compared to what alternatives and why. -> AUGMENTED CODE + MAINTAIN A BLOG 29 | - But don't try to capture every event; instead rewrite the story to make it simpler and shorter (like Git history with rebase) 30 | -------------------------------------------------------------------------------- /manuscript/_content_overview.txt: -------------------------------------------------------------------------------- 1 | What's differentiating in this book? Stuff (techniques and ideas) that's not common and almost unpublished so far 2 | 3 | - generic principles to evaluate if a particular technique is really up to the living documentation standard, and to improve it if needed 4 | - living glossary: useful for DDD 5 | - living diagram: the technique, and the examples of "what for 6 | - Visible (Introspectable) Workings: tree dump, formula, monad-ish, http://blog.jonudell.net/2008/03/04/ward-cunninghams-visible-workings/ 7 | - "all knowledge directly in the code" approach, with augmented code 8 | - the insightful aspects of documentation, how it helps reflect on what's been done in order to improve it, not just after but *during* the development work 9 | - conversations matter most, and when there's no need for documentation 10 | - how to make documentation reliable, the two approaches 11 | - how to make documentation change-friendly 12 | - living enterprise architecture, in the large 13 | - automate and enforce over guides and guidelines, fix the trouble over documentation of the troubles 14 | - test curation: making documentation more interesting through careful curation 15 | - findable knowledge: a search engine is a very documentation system 16 | - lean on your tools: built-in search, type hierarchy, calls stack, link navigation of your IDE 17 | - other tips and tricks and a set of principles expressed as Preferences, and some weird ideas like using unorthodox media to help communication and collaboration, and some theory 18 | - a bonus: examples carefully chosen to also suggest better design decisions, inspired by DDD; a mini recap of the true BDD approach 19 | -------------------------------------------------------------------------------- /manuscript/_encoding_characters_to_escape.txt: -------------------------------------------------------------------------------- 1 | – 2 | ’ 3 | “ 4 | â€TM 5 | 6 | ClÃmo Charnay 7 | In the following chapters weâ€TMll describe 8 | DDD advocates “Modeling with codeâ€� as 9 | -------------------------------------------------------------------------------- /manuscript/_imported/_domain_knowledge.txt: -------------------------------------------------------------------------------- 1 | # Documenting the business knowledge 2 | 3 | 4 | 5 | ## Scenario's Digest 6 | annotate scenarios with intrinsic properties: nominal, sexy... so that to automatically extract a digest of them for a particular editorial purpose: user manual, stakeholders-specific documentation, one-tip-a-day etc 7 | 8 | ## Code Digest 9 | Not all code is worth reading. Books typically show some very cleaned-up version 10 | 11 | ## Signal Noise Ratio & other metrics to monitor 12 | DDD tactical patterns, Clean Code 13 | 14 | Compute alignment metrics: 15 | - outbound dependencies to deprecated stuff 16 | - total inbound dependencies to deprecated stuff 17 | - ratio of words from Ubiquitous Language within scenarios or other general text documentation 18 | - broken links 19 | - word clouds & missing definition for lost popular words 20 | - rate of technical jargon within Ubiquitous Language etc, as defined from blacklists 21 | - violations of rules etc 22 | 23 | 24 | ## Compiled Sample Code 25 | Don't manually copy paste sample code, embed a link to code actually compiled. This applies to user guides and Javadoc-like comments. 26 | 27 | ## Curated Datasets 28 | Carefully selected Datasets that represent a specific situation of interests. It may be typical, or extreme, or whatever is of interest from a business domain standpoint. Curated or Generated Datasets can be named and can belong to the Ubiquitous Language. 29 | 30 | 31 | ## Visible Tests 32 | Tests that produce an output for human review 33 | 34 | -- 35 | 36 | 37 | Living Glossary examples 38 | 39 | Festival ticketing system: festival series, festival event, location, partners, capacity, overbooking strategy, pricing strategy (over time), line-up, ticket (unique id), ticket, legal notes // from kickstart example 40 | -------------------------------------------------------------------------------- /manuscript/_imported/_quote_twitter_convo_code_tells_WHAT_HOW_NOT_WHY.txt: -------------------------------------------------------------------------------- 1 | > Document WHY things are what they are, and not WHAT they are -- Robert Virding at a conference 2 | 3 | If @rvirding didn't mean this as a direct message to Haskell library writers, he should have. -- @bodil tweeting about the conference 4 | 5 | this is actually why I'm against religious "code is your documentation". Because code is the what and not the why. -- ‏@karlprosser 6 | 7 | I'd still believe that excellent code already tells 'what' and 'why'. The problem lies in 'why not' missing. -- Jonne Itkonen ‏@batalyx 8 | 9 | 10 | Don't agree with you. Excellent code will tell you 'what' and maybe explain 'how' http://www.geekherocomic.com/2008/11/12/real-programmers-dont-write-documentation/ -- Robert Virding ‏@rvirding 11 | 12 | @rvirding @bodil don't get me wrong. Code is the only source of real truth of what and how, but often the nuances of why are lost in folklore -- @karlprosser 13 | 14 | ... 15 | 16 | The story @rvirding just shared was one where they thought the why was obvious but it wasn't. 17 | 18 | 19 | @karlprosser @bodil @rvirding but the why is frequently inarticulate screaming, which is hard to serialized as ASCII -- Gary Bernhardt ‏@garybernhardt 20 | 21 | that's why we now have emoji -- @hirojin 22 | 23 | ... 24 | 25 | "Because [Regulatory Compliance Guy] says so" is the most common comment in our code base. 26 | 27 | Code should ideally self-document *what* it's doing (it should be clear what). But that's only a part of docs. -- Anthony Ferrara ‏@ircmaxell 28 | 29 | "Things that are not documentation” - http://www.drmaciver.com/2015/04/things-that-are-not-documentation/ - Kristian Glass ‏@doismellburning 30 | 31 | 32 | Code is the most reliable documentation, not the best one. Of course, the "Why" isn't always clear -- Claudio Zizza ‏@SenseException 33 | -------------------------------------------------------------------------------- /manuscript/_imported/_tools.txt: -------------------------------------------------------------------------------- 1 | # Tools for Living Documentation 2 | 3 | 4 | -- 5 | 6 | At the time of writing, here are some of the available tools of particular interest for living documentation. 7 | 8 | - Your programming language (s) and its extension capabilities 9 | - 10 | 11 | 12 | 13 | ASCII, little syntax, diagrammr, dot 14 | 15 | - Cucumber, SpecFlow, DaSpec 16 | - Markdown 17 | - Graphviz 18 | - Wordcloud 19 | 20 | 21 | Swagger 22 | 23 | - Maven site 24 | - Maven Tree 25 | - all CD tools 26 | 27 | 28 | 29 | Svg, Graphviz, pandoc, js, neo4j, dataviz 30 | 31 | - Markdown, yaml, even json for the content in itself, plus tools to render that into other documents 32 | - interactive slideshow from markdown files with Reveal.js 33 | - ASCIIDoc 34 | - d3.js 35 | 36 | - Diagrammr-like 37 | - Structurizr 38 | 39 | 40 | 41 | - custom parser 42 | 43 | 44 | -- 45 | from peter hilton 46 | 47 | Use Markdown or similar Things that seemed like a good idea at the time: troff, SGML, RTF, DocBook, XHTML, XSL-FO 48 | Things that seem like a better idea now: Markdown, reStructuredText, AsciiDoc 49 | The ultimate text markup language is still: HTML 50 | 51 | GitHub repo - plain Markdown files 52 | GitHub Pages - Jekyll site builder 53 | GitHub Wiki - Gollum wiki 54 | Read the Docs - Sphinx docs builder 55 | Asciidoctor - asciidoc to many formats 56 | Swagger - API docs structure and layout 57 | Silk - API docs 58 | --- 59 | literate programming 60 | 61 | Arnaud Bailly 62 | 63 | Extract the Clojure code to convert it into Latex (not ideal but working) 64 | 65 | https://github.com/kovasb/session 66 | 67 | Brute force solution as an oracle & as more accessible documentation 68 | 69 | Formula in fitness + reconciliation of the test against the actual code; 70 | Excel sheet as the actual reference: why copy-paste and lose the formula? Alternative formula as an oracle. 71 | -- 72 | https://github.com/gdeer81/marginalia 73 | -------------------------------------------------------------------------------- /manuscript/_imported/capture_ideas.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/capture_ideas.png -------------------------------------------------------------------------------- /manuscript/_imported/explore_ideas.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/explore_ideas.png -------------------------------------------------------------------------------- /manuscript/_imported/highlighted_core_eclipse_search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/highlighted_core_eclipse_search.png -------------------------------------------------------------------------------- /manuscript/_imported/phases-1-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/phases-1-2.png -------------------------------------------------------------------------------- /manuscript/_imported/phases-3-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/phases-3-4.png -------------------------------------------------------------------------------- /manuscript/_imported/present_ideas.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/present_ideas.png -------------------------------------------------------------------------------- /manuscript/_imported/sales_funnel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/sales_funnel.png -------------------------------------------------------------------------------- /manuscript/_imported/system_diagram_flottio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/_imported/system_diagram_flottio.png -------------------------------------------------------------------------------- /manuscript/backmatter.txt: -------------------------------------------------------------------------------- 1 | {backmatter} 2 | -------------------------------------------------------------------------------- /manuscript/bdd/Section------LivingDocumentationBDDExample.txt: -------------------------------------------------------------------------------- 1 | -# Part 2 Living Documentation exemplified by Behavior-Driven Development 2 | -------------------------------------------------------------------------------- /manuscript/bdd/_DocumentingBusinessBehavior.txt: -------------------------------------------------------------------------------- 1 | # Documenting Business Behavior 2 | 3 | With BDD and specification by examples you get living documentation for each example or scenario. Thanks to automation, if the code of the scenario becomes out-of-sync, some tests fail and tell us we need to fix the discrepancy. 4 | 5 | But in many complex cases the scenarios are not enough to explain all the behavior, you need higher-level description in the form of rules, maths formula or principles. 6 | 7 | Many write that kind of knowledge in a wiki. The problem of a wiki is that it lives in a distinct space time. It has its own structure, and its own distinct lifecycle. You often need to use the search feature to find the right answer quickly, and the probability to forget to update the wiki when you update the code or the scenarios is quite high. Lastly, a wiki has its own distinct scheme of versioning. 8 | 9 | - Collocation 10 | - Companion markdown file with same name 11 | - Trigger on commit "You changed the scenario without changing the companion file, did you check they are still in sync?" 12 | - Wiki on same source control and with same organizing structure than the BDD scenarios 13 | - run code and insert the results (self-explaining formula, object graph, config...) into the documentation a la Dexy 14 | 15 | -- 16 | Standalone set of scenario titles 17 | The set of scenario titles can be understood without looking at the content and gives a good idea of the functional coverage of the scenarios 18 | 19 | No duplication between the scenario title and its content 20 | Don't repeat what the scenario does in its title 21 | 22 | Higher level of abstraction in the scenario name compared to the content 23 | The title provides a higher-level describtion of what the scenario intends to do. 24 | 25 | Scenarios tests as a system 26 | 27 | Feature describes the context and the perspective every scenario belongs to; each scenario only has to locate itself within this perspective 28 | 29 | E.g. A given B and C, or B given A and C… 30 | 31 | Features files as substitutes for specifications (?) 32 | It is legal to embed a few paragraphs to describe the expected behavior from a higher-level point of view, including formula and links to external resources and diagrams. 33 | -------------------------------------------------------------------------------- /manuscript/bdd/_more_BDD_examples.txt: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /manuscript/bdd/images/3amigos.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/bdd/images/3amigos.png -------------------------------------------------------------------------------- /manuscript/bdd/images/bdd-reconciliation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/bdd/images/bdd-reconciliation.jpg -------------------------------------------------------------------------------- /manuscript/bdd/images/bdd-redundancy.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/bdd/images/bdd-redundancy.jpg -------------------------------------------------------------------------------- /manuscript/bdd/images/bdd-website.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/bdd/images/bdd-website.jpg -------------------------------------------------------------------------------- /manuscript/courtesy_TODO.txt: -------------------------------------------------------------------------------- 1 | 2 | Cucumber, Specflow logos 3 | Pickles screenshot 4 | ask Alistair for hexagonal diagram, modes of communication diagram 5 | 6 | https://github.com/gojko/bugmagnet/blob/master/screenshots/header-menu.png 7 | 8 | excessive uml diagram 9 | meme generator Living Doc 10 | 11 | puppet-graph-complex.png diagram from http://bitfieldconsulting.com/puppet-dependency-graphs 12 | 13 | Q: ask review by JHipster 14 | 15 | Q: as far as I know there's little we can do to extend the Maven XML with additional knowledge about each dependency. 16 | -------------------------------------------------------------------------------- /manuscript/frontmatter.txt: -------------------------------------------------------------------------------- 1 | {frontmatter} 2 | -------------------------------------------------------------------------------- /manuscript/images/3amigos.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/3amigos.png -------------------------------------------------------------------------------- /manuscript/images/4-principles.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/4-principles.png -------------------------------------------------------------------------------- /manuscript/images/4_principles.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/4_principles.jpg -------------------------------------------------------------------------------- /manuscript/images/ConsolidatedView.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/ConsolidatedView.jpg -------------------------------------------------------------------------------- /manuscript/images/ConversationsTraces.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/ConversationsTraces.jpg -------------------------------------------------------------------------------- /manuscript/images/DocumentationDefinition.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/DocumentationDefinition.jpg -------------------------------------------------------------------------------- /manuscript/images/EnforcedArchitecture.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/EnforcedArchitecture.jpg -------------------------------------------------------------------------------- /manuscript/images/EnforcedArchitecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/EnforcedArchitecture.png -------------------------------------------------------------------------------- /manuscript/images/JB1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/JB1.png -------------------------------------------------------------------------------- /manuscript/images/JB2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/JB2.png -------------------------------------------------------------------------------- /manuscript/images/JB3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/JB3.png -------------------------------------------------------------------------------- /manuscript/images/JB4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/JB4.png -------------------------------------------------------------------------------- /manuscript/images/LD_map.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/LD_map.png -------------------------------------------------------------------------------- /manuscript/images/ReadyForExtension.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/ReadyForExtension.jpg -------------------------------------------------------------------------------- /manuscript/images/Reconciliation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/Reconciliation.jpg -------------------------------------------------------------------------------- /manuscript/images/Reconciliation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/Reconciliation.png -------------------------------------------------------------------------------- /manuscript/images/alistair_hexagonal.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/alistair_hexagonal.gif -------------------------------------------------------------------------------- /manuscript/images/alistair_hexagonal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/alistair_hexagonal.png -------------------------------------------------------------------------------- /manuscript/images/annotation_tooltip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/annotation_tooltip.png -------------------------------------------------------------------------------- /manuscript/images/areyouawesome.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/areyouawesome.jpg -------------------------------------------------------------------------------- /manuscript/images/arrange_act_assert.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/arrange_act_assert.png -------------------------------------------------------------------------------- /manuscript/images/augmented_code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/augmented_code.png -------------------------------------------------------------------------------- /manuscript/images/bc1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/bc1.png -------------------------------------------------------------------------------- /manuscript/images/bc2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/bc2.png -------------------------------------------------------------------------------- /manuscript/images/bdd-reconciliation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/bdd-reconciliation.jpg -------------------------------------------------------------------------------- /manuscript/images/bdd-redundancy.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/bdd-redundancy.jpg -------------------------------------------------------------------------------- /manuscript/images/bdd-website.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/bdd-website.jpg -------------------------------------------------------------------------------- /manuscript/images/biodegradabledoc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/biodegradabledoc.png -------------------------------------------------------------------------------- /manuscript/images/brain_dump.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/brain_dump.png -------------------------------------------------------------------------------- /manuscript/images/cash_timeline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/cash_timeline.png -------------------------------------------------------------------------------- /manuscript/images/chore_automation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/chore_automation.png -------------------------------------------------------------------------------- /manuscript/images/codex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/codex.png -------------------------------------------------------------------------------- /manuscript/images/color-coded-pompidou.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/color-coded-pompidou.png -------------------------------------------------------------------------------- /manuscript/images/command-event-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/command-event-diagram.png -------------------------------------------------------------------------------- /manuscript/images/composed_method_by_abstraction.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/composed_method_by_abstraction.png -------------------------------------------------------------------------------- /manuscript/images/consolidation_mechanism.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/consolidation_mechanism.jpg -------------------------------------------------------------------------------- /manuscript/images/copist.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/copist.png -------------------------------------------------------------------------------- /manuscript/images/curator.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/curator.png -------------------------------------------------------------------------------- /manuscript/images/decantation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/decantation.png -------------------------------------------------------------------------------- /manuscript/images/diagram_communication_modes_alistair_cockburn.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/diagram_communication_modes_alistair_cockburn.gif -------------------------------------------------------------------------------- /manuscript/images/diagram_communication_modes_alistair_cockburn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/diagram_communication_modes_alistair_cockburn.png -------------------------------------------------------------------------------- /manuscript/images/diagrammr1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/diagrammr1.png -------------------------------------------------------------------------------- /manuscript/images/diagrammr2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/diagrammr2.png -------------------------------------------------------------------------------- /manuscript/images/domain-specific-svg1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/domain-specific-svg1.png -------------------------------------------------------------------------------- /manuscript/images/domain-specific-svg2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/domain-specific-svg2.png -------------------------------------------------------------------------------- /manuscript/images/dotdiagram_rendering.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/dotdiagram_rendering.png -------------------------------------------------------------------------------- /manuscript/images/eclipse_pom_navigation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/eclipse_pom_navigation.png -------------------------------------------------------------------------------- /manuscript/images/element_of_a_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/element_of_a_system.png -------------------------------------------------------------------------------- /manuscript/images/enum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/enum.png -------------------------------------------------------------------------------- /manuscript/images/exemplar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/exemplar.png -------------------------------------------------------------------------------- /manuscript/images/explore-capture-present.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/explore-capture-present.png -------------------------------------------------------------------------------- /manuscript/images/fool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/fool.png -------------------------------------------------------------------------------- /manuscript/images/foyer.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/foyer.jpg -------------------------------------------------------------------------------- /manuscript/images/github_blame_view.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/github_blame_view.png -------------------------------------------------------------------------------- /manuscript/images/goals/impact_map_micro_royalties.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/goals/impact_map_micro_royalties.png -------------------------------------------------------------------------------- /manuscript/images/gofastgowell.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/gofastgowell.jpg -------------------------------------------------------------------------------- /manuscript/images/header-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/header-menu.png -------------------------------------------------------------------------------- /manuscript/images/hexagonal-sketch.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/hexagonal-sketch.jpg -------------------------------------------------------------------------------- /manuscript/images/hexagonal.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/hexagonal.jpg -------------------------------------------------------------------------------- /manuscript/images/hexagonal_living-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/hexagonal_living-diagram.png -------------------------------------------------------------------------------- /manuscript/images/hexagonal_living-diagram.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/hexagonal_living-diagram.tif -------------------------------------------------------------------------------- /manuscript/images/highlighted_core_eclipse_search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/highlighted_core_eclipse_search.png -------------------------------------------------------------------------------- /manuscript/images/introspectable-generated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/introspectable-generated.png -------------------------------------------------------------------------------- /manuscript/images/introspectable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/introspectable.png -------------------------------------------------------------------------------- /manuscript/images/introspecting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/introspecting.png -------------------------------------------------------------------------------- /manuscript/images/james_lewis_cloud_diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/james_lewis_cloud_diagram.png -------------------------------------------------------------------------------- /manuscript/images/legacy_annotation_registry.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_annotation_registry.jpg -------------------------------------------------------------------------------- /manuscript/images/legacy_bad_modules.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_bad_modules.jpg -------------------------------------------------------------------------------- /manuscript/images/legacy_bubble_context.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_bubble_context.jpg -------------------------------------------------------------------------------- /manuscript/images/legacy_expected_vs_actual.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_expected_vs_actual.jpg -------------------------------------------------------------------------------- /manuscript/images/legacy_expected_vs_actual.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_expected_vs_actual.png -------------------------------------------------------------------------------- /manuscript/images/legacy_modules_mapping.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_modules_mapping.jpg -------------------------------------------------------------------------------- /manuscript/images/legacy_strangled_app.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/legacy_strangled_app.jpg -------------------------------------------------------------------------------- /manuscript/images/likecounter.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/likecounter.jpg -------------------------------------------------------------------------------- /manuscript/images/listen_to_doc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/listen_to_doc.png -------------------------------------------------------------------------------- /manuscript/images/living-diagram-1-story.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living-diagram-1-story.png -------------------------------------------------------------------------------- /manuscript/images/living-diagram1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living-diagram1.jpg -------------------------------------------------------------------------------- /manuscript/images/living-diagram2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living-diagram2.jpg -------------------------------------------------------------------------------- /manuscript/images/living_diagram_overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living_diagram_overview.png -------------------------------------------------------------------------------- /manuscript/images/living_documentation_map.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living_documentation_map.jpg -------------------------------------------------------------------------------- /manuscript/images/living_documentation_map.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living_documentation_map.png -------------------------------------------------------------------------------- /manuscript/images/living_glossary_overview.015.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living_glossary_overview.015.jpg -------------------------------------------------------------------------------- /manuscript/images/living_glossary_overview.016.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/living_glossary_overview.016.jpg -------------------------------------------------------------------------------- /manuscript/images/livingdoc_doc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/livingdoc_doc.png -------------------------------------------------------------------------------- /manuscript/images/matching_expressions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/matching_expressions.png -------------------------------------------------------------------------------- /manuscript/images/megaphone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/megaphone.png -------------------------------------------------------------------------------- /manuscript/images/misleading_label.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/misleading_label.png -------------------------------------------------------------------------------- /manuscript/images/musictheory_treeview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/musictheory_treeview.png -------------------------------------------------------------------------------- /manuscript/images/napkin_sketch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/napkin_sketch.png -------------------------------------------------------------------------------- /manuscript/images/nodocumentation.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/nodocumentation.jpg -------------------------------------------------------------------------------- /manuscript/images/noprojects_poster.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/noprojects_poster.jpg -------------------------------------------------------------------------------- /manuscript/images/one-diagram-one-story.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/one-diagram-one-story.png -------------------------------------------------------------------------------- /manuscript/images/orderbook_table.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/orderbook_table.jpg -------------------------------------------------------------------------------- /manuscript/images/originals/alistair_hexagonal.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/originals/alistair_hexagonal.gif -------------------------------------------------------------------------------- /manuscript/images/originals/diagram_communication_modes_alistair_cockburn.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/originals/diagram_communication_modes_alistair_cockburn.gif -------------------------------------------------------------------------------- /manuscript/images/out_of_sync.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/out_of_sync.png -------------------------------------------------------------------------------- /manuscript/images/over-complicated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/over-complicated.png -------------------------------------------------------------------------------- /manuscript/images/overview.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/overview.jpg -------------------------------------------------------------------------------- /manuscript/images/package-annotations.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/package-annotations.png -------------------------------------------------------------------------------- /manuscript/images/packages.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/packages.png -------------------------------------------------------------------------------- /manuscript/images/pasted-image-6633.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/pasted-image-6633.png -------------------------------------------------------------------------------- /manuscript/images/phd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/phd.png -------------------------------------------------------------------------------- /manuscript/images/procrastination.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/procrastination.png -------------------------------------------------------------------------------- /manuscript/images/puppet-graph-complex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/puppet-graph-complex.png -------------------------------------------------------------------------------- /manuscript/images/rate_of_change.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rate_of_change.png -------------------------------------------------------------------------------- /manuscript/images/reconciliation_mechanism.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/reconciliation_mechanism.jpg -------------------------------------------------------------------------------- /manuscript/images/rendered1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rendered1.png -------------------------------------------------------------------------------- /manuscript/images/rendered2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rendered2.png -------------------------------------------------------------------------------- /manuscript/images/rendered2bis.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rendered2bis.png -------------------------------------------------------------------------------- /manuscript/images/rendered3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rendered3.png -------------------------------------------------------------------------------- /manuscript/images/rendered4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rendered4.png -------------------------------------------------------------------------------- /manuscript/images/rendered_later.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/rendered_later.png -------------------------------------------------------------------------------- /manuscript/images/robots1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/robots1.jpg -------------------------------------------------------------------------------- /manuscript/images/robots2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/robots2.jpg -------------------------------------------------------------------------------- /manuscript/images/sales_funnel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/sales_funnel.png -------------------------------------------------------------------------------- /manuscript/images/scribes_copying.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/scribes_copying.jpg -------------------------------------------------------------------------------- /manuscript/images/separate_activities.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/separate_activities.jpg -------------------------------------------------------------------------------- /manuscript/images/single_source_multiple_outputs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/single_source_multiple_outputs.png -------------------------------------------------------------------------------- /manuscript/images/single_sourcing_mechanism.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/single_sourcing_mechanism.jpg -------------------------------------------------------------------------------- /manuscript/images/sonar_rules.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/sonar_rules.jpg -------------------------------------------------------------------------------- /manuscript/images/sonarreference.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/sonarreference.png -------------------------------------------------------------------------------- /manuscript/images/source_code_icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/source_code_icon.png -------------------------------------------------------------------------------- /manuscript/images/supplychain.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/supplychain.png -------------------------------------------------------------------------------- /manuscript/images/system_diagram_flottio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/system_diagram_flottio.png -------------------------------------------------------------------------------- /manuscript/images/system_diagram_flottio2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/system_diagram_flottio2.png -------------------------------------------------------------------------------- /manuscript/images/table_code_layout.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/table_code_layout.png -------------------------------------------------------------------------------- /manuscript/images/timesink.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/timesink.png -------------------------------------------------------------------------------- /manuscript/images/title_page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/title_page.png -------------------------------------------------------------------------------- /manuscript/images/title_page_old.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/title_page_old.jpg -------------------------------------------------------------------------------- /manuscript/images/transparent_architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/transparent_architecture.png -------------------------------------------------------------------------------- /manuscript/images/tshirt.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/tshirt.jpg -------------------------------------------------------------------------------- /manuscript/images/type_signature_search.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/type_signature_search.png -------------------------------------------------------------------------------- /manuscript/images/type_signature_search_int.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/type_signature_search_int.png -------------------------------------------------------------------------------- /manuscript/images/uml_class_notation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/uml_class_notation.png -------------------------------------------------------------------------------- /manuscript/images/useless-uml-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/useless-uml-diagram.png -------------------------------------------------------------------------------- /manuscript/images/visible_hygiene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/visible_hygiene.png -------------------------------------------------------------------------------- /manuscript/images/vo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/vo.png -------------------------------------------------------------------------------- /manuscript/images/what_were_they_thinking.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/what_were_they_thinking.png -------------------------------------------------------------------------------- /manuscript/images/why_so_complicated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/why_so_complicated.png -------------------------------------------------------------------------------- /manuscript/images/without_why_same_mistake_again.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/without_why_same_mistake_again.png -------------------------------------------------------------------------------- /manuscript/images/wordcloud_bad.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/wordcloud_bad.png -------------------------------------------------------------------------------- /manuscript/images/wordcloud_good.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/wordcloud_good.png -------------------------------------------------------------------------------- /manuscript/images/zipkin_deps_tracegen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/images/zipkin_deps_tracegen.png -------------------------------------------------------------------------------- /manuscript/indexoutline_TODO.txt: -------------------------------------------------------------------------------- 1 | 2 | # Living Documentation 3 | 4 | Reliable 5 | Accurate 6 | 7 | (… All patterns from this book) 8 | 9 | 10 | # Books and Online articles 11 | 12 | (… All references) 13 | 14 | # Authors 15 | 16 | (… All authors) 17 | 18 | # Authors patterns 19 | 20 | (… All patterns from other books that are mentioned in this book) 21 | 22 | 23 | # Methodologies 24 | 25 | ## Agile Approaches 26 | XP 27 | Scrum 28 | Waterfall 29 | 30 | ## Software Craftsmanship Practices 31 | 32 | Domain-Driven Design 33 | TDD 34 | BDD 35 | ATDD 36 | 37 | Coding Dojo 38 | Koans 39 | Codeanalysis 40 | Whiteboard 41 | Event Storming 42 | Model Storming 43 | 44 | 45 | # Development Activity 46 | 47 | ## Requirement Elicitation 48 | Acceptance Criteria 49 | Acceptance Test 50 | 3 amigos 51 | Specification workshops 52 | Concrete Examples 53 | 54 | ## Testing 55 | 56 | Unit Test 57 | Mocking 58 | Fluent Test 59 | Test Coverage 60 | Test Automation 61 | 62 | ## Coding 63 | 64 | Clean Code 65 | Pair-Programming 66 | Cross-Programming 67 | Mob-Programming 68 | IDE 69 | Java Programming Language 70 | C# Programming Language 71 | Clojure Programming Language 72 | F# Programming Language 73 | 74 | 75 | ## Design 76 | 77 | Refactoring 78 | Design Patterns 79 | 80 | ## Dependency Management 81 | 82 | Maven 83 | Gradle 84 | sbt 85 | … 86 | 87 | 88 | ## Infrastructure 89 | 90 | Puppet, Chef, Ansible, Salt 91 | 92 | ## Deployment 93 | 94 | Octopus Deploy 95 | 96 | ## Monitoring 97 | 98 | Nagios 99 | 100 | 101 | # Language 102 | 103 | Ubiquitous Language 104 | Visual layout 105 | 106 | DSL 107 | 108 | # Media 109 | 110 | - Information Radiators 111 | - Electronic propaganda: banners on build walls, wallpaper, idle screens, pair-programming blocker screens 112 | - Maxims 113 | - Wifi names and passwords 114 | - Goodies: T-shirts, mugs 115 | - Posters 116 | - Infodecks 117 | - Drawing 118 | - Collage of stuff found on the Internet 119 | - Comics 120 | - Cheat Sheet 121 | - Card Decks 122 | - Visualizations & Animations 123 | - Company blog 124 | - Company chat, chatbot 125 | - knowledge base 126 | - Congruent Media 127 | - Gamification 128 | - Tangible Media 129 | -------------------------------------------------------------------------------- /manuscript/mainmatter.txt: -------------------------------------------------------------------------------- 1 | {mainmatter} 2 | -------------------------------------------------------------------------------- /manuscript/megaphone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyriux/livingdocumentation-thebook/9243b810e64b1380c551ad2681262801d8542c8b/manuscript/megaphone.png -------------------------------------------------------------------------------- /manuscript/releasenotes_TODO.txt: -------------------------------------------------------------------------------- 1 | 2 | curation + scenario digest 3 | intrinsic 4 | 5 | ======= Feb 2017 6 | 7 | 8 | Dear readers, 9 | Thanks for your support on this book! I'm happy to give you some news about the book Living Documentation. It has grown a lot over the last months, with 400 pages now. Many new chapters and sections were added. 10 | 11 | All the content is mostly there now. the completion rate is only 99% because it should still get some editing to fix typos, improve the writing style and remove extraneous verbiage. 12 | 13 | Also, some big news 14 | 15 | 16 | 17 | Cyrille 18 | 19 | 20 | Introduction/KnowledgeLifecycle.txt 21 | Introduction/Checklist.txt 22 | Introduction/_Overview.txt 23 | ---Problem, WhatIsDocumentation (soon: CorePrinciples) 24 | KnowledgeExploitation/ReadyMadeKnowledge.txt 25 | NoDocumentation/Conversations.txt 26 | NoDocumentation/WorkingCollectively.txt 27 | NoDocumentation/DeclarativeAutomation.txt 28 | EfficientDocumentation/StackOverflowDocumentation.txt 29 | EfficientDocumentation/SpecificationWorkshops.txt 30 | EfficientDocumentation/SmallScaleSimulation.txt -> 31 | Introduction_Overview/SpineModel.txt 32 | 33 | KnowledgeExploitation/SingleSourcing.txt 34 | KnowledgeExploitation/Reconciliation.txt 35 | KnowledgeExploitation/InformationConsolidation.txt 36 | 37 | + 38 | RefactorableDocumentation/CodeAsDocumentation.txt 39 | RefactorableDocumentation/TypeDrivenDocumentation.txt 40 | RefactorableDocumentation/ComposedMethod.txt 41 | RefactorableDocumentation/FluentStyle.txt 42 | RefactorableDocumentation/RefactoringGuidedByComments.txt 43 | RefactorableDocumentation/PlainTextDiagram.txt // TODO add code sample to generate one (Diagrammr is dead) 44 | 45 | RefactorableDocumentation/DiagramInCode.txt //pending 46 | 47 | ============== 48 | June 30th 49 | 50 | + KnowledgeAugmentation/DocumentationByConvention.txt 51 | + BDD made a real chapter 52 | + LivingDocumentation/HexagonalArchitectureDiagram.txt 53 | + Beyond Doc: 54 | + Abusing LD 55 | + Listen to the doc 56 | + Deliberate Design 57 | + Biodegradable doc 58 | + Hygienic Transparency 59 | + Enforced Guidelines 60 | 61 | ============== 62 | STATUS: 63 | 64 | Publisher ideal is 288 pages (270 - 320 pages, including biblio and index, around 10-20 pages, not so much needed for an e-book) 65 | 66 | Publisher ideal = 90 - 100K words 67 | 68 | Sandro Book: 83K words 69 | 70 | About 30 lines per page 71 | -------------------------------------------------------------------------------- /manuscript/update_images.txt: -------------------------------------------------------------------------------- 1 | cp */images/* images --------------------------------------------------------------------------------