Living Documentation

Tu ne le sais pas encore, mais tu l’as deja documenté !

Qui suis-je ?

Marc Bouvier

marc bouvier rnd 25

About this presentation

  • Présentation et sources en ligne

QR Code vers le lien de la présentation : u.baldir.fr/at-2021-ld

Déconstruisons la documentation

La documentation, c’est quoi pour vous?

Word Cloud

Pour qui?

  • Métier

  • Utilisateurs (embedded tooltip)

  • Développeurs (internes)

  • Développeurs (externes)

  • Régulateur

Pourquoi?

  • Onboarding

  • Readme

  • Contribute

  • CodeTour

Comment?

  • Ecrit? Non écrit?

  • Conversations (ex. pour onboarding)

  • Conversations over Documentation

  • Travailer ensemble

  • Pair programming / Mob programmgin

  • Interviews métier, immersion

  • Code

  • Commentaires → refactor

  • Code = documentation

  • nommage : classes, packages, fonctions

  • annotations et métadonnées

  • DDD

  • tests

  • TDD

  • BDD

De nouvelles approches de la documentation

En bref

  • NoDocumentation

  • Stable Documentation

  • Refactor-Friendly Documentation

  • Automated Documentation

  • Runtime Documentation

  • Beyond Documentation

TODO : Déconstruisons le concept de documentation

Core Principles of Living Documentation

  • Reliable *

Documentation Smells

Like cheap wine, paper documentation ages rapidly and leaves you with bad headache.
Specification by Example: How Successful Teams Deliver the Right Software
— Gojko Adzic

Activités séparées

TODO trouver GIF

Java 18 Javadoc Code Snippets

package fr.baldir.samples.hello;

public class Hello {
    /**
     * Greets someone.
     * <p>Usage</p>
     * {@snippet class="snippets.SnippetTest" region="test-region"}
     *
     * @param name target of greetings
     * @return full greeting sentence
     */
    public String sayHello(String name) {
        return "Hello " + name;
    }
}
package snippets;

import fr.baldir.samples.hello.Hello;
import org.assertj.core.api.Assertions;
import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;


public class SnippetTest {

    @Test
    public void someTest() {
        // @start region="test-region"
        Hello hello = new Hello();
        var greetings = hello.sayHello("JEP 413");
        // @end
        Assertions.assertThat(greetings).isEqualTo("Hello JEP 413");
    }
}

101 generated javadoc result

Attributes

  • Internal documentation

  • in-situ

  • machine-readable

Attributes

  • refactor-friendly

  • automated documentation

  • low effort

Resources

Plain text

  • Versionnable

  • Lisible par un humain

Markdown

  • primitive lightweight syntax

  • embed HTML

  • Github

  • Repo

  • Pages

  • Azure DevOps

  • Wiki as code

Markdown pros/cons

Pros

  • primitive syntax

  • supported everywhere

Cons

  • Flavour hell

  • not much advanced features

  • embed HTML if

Asciidoc

Asciidoc pros/cons

Pros

Living Diagram

Living glossary

Living onboarding

Wiki

Capture of Dan North’s

Code Driven Guided tour

GUI Driven

  • With High level automated GUI tests

Collaboration driven

  • Live my life (immersion with/as business)

  • pair programming

  • mob programming

Tests as documentation

Spring

Spring Rest Docs

Automated Release notes

Unresolved directive in slides.adoc - include::15_specifications_as_code.adoc[]

Unresolved directive in slides.adoc - include::16_strategy_for_devops.adoc[]

Unresolved directive in slides.adoc - include::17_notebooks.adoc[]

Unresolved directive in slides.adoc - include::18_declarative_infrastructure.adoc[]

Unresolved directive in slides.adoc - include::19_dsl.adoc[]

Unresolved directive in slides.adoc - include::20_hard_to_generate_diagram_is_a_signal.adoc[]

Mais au fait, elle fait quoi notre application?

  • Manuel utilisateur

  • OpenApi / Swagger

  • Javadoc

  • Site web

  • Readme.md

  • Demo site = documentation

Demo CodeTour

  • Versionné

  • Peut être validé quand le code change

  • Json

  • Peut servir de base pour d’autres automatisations

  • Exemple

Doctest

Python Elixir

import in markup

  • AsciiDoc

  • LateX

La doc s’appuie sur votre code (ex. .env sample)

Différentes caractéristiques

  • Stable

TODO : tableau

  • Statique, immuable, standard

  • Dynamique, change souvent

Evergreen document Ce qui est stable = ce qui est toujours vrai

tout ce qui bouge ailleurs

  • marketing

  • noms de sociétés

  • les dates

  • les gens

Les comportements métiers

BDD

Documentation exécutable

Redondance

Quelle est la source de vérité?

Cucumber / Specflow → réconciliation entre scénarios et code

Désastre d’automatisation illustré par une usine automatique comportant des centaines de tapis roulant et des cheminées industrielles rejetant une épaisse fumée noire

Automatisation : ça tourne mal

Source : I Built a 600 Meter Human Cannon That Ends All Existence - Satisfactory - Let's Game It Out - 2020

DRY - Aussi pour la documentation

  • Single source of source

  • Plusieurs cibles de documentation possibles

A partir du code source de la classe Intr en Kotlin

Des nouvelles façons de documenter

Notebooks

Tests as documentation

Elixir Doctest

Rust Documentation tests

Contributif

Wiki as code

VueJs propose de mettre à jour sa documentation par PR <p style="font-size: 1rem">Source : <a href="https://vuejs.org/v2/guide">https://vuejs.org/v2/guide</a></p>

Documenter pendant

  • TDD

  • Documenter l’intention, le comportement

Conclusion

Les slides

qrcode u.baldir.fr AT2021LD]

La documentation c’est quoi pour vous?

Ressources

Living Documentation - Cyrille Martraire

Living Documentation - Cyrille Martraire ([@cyriux](https://twitter.com/cyriux))

[Living Documentation : vous allez aimer la documentation !(Cyrille Martraire)](https://www.youtube.com/watch?v=Tw-wcps7WqU)

![Quelques livres de Gojko Adzic dont : "Impact Mapping", "Specification By Example", "Fifty Quick Ideas to Improve Your User Stories", "Bridging the Communication Gap: Specification by Example and Agile Acceptance Testing", "Fifty Quick Ideas To Improve Your Tests"](assets/Gojko_Adzic.png)

Gifs