the_problem_with_traditional_documentation.adoc

The problem with traditional documentation

Not very reliable

• Usually external documents

• Not in sync with the system

• Versioning hell

Separate activities

Specs 👨‍💼

Code 👩‍💻

️Tests 🕵️‍

Doc 👩‍🏫

Even in Agile teams!

• Beaucoup de temps et d’opportunités perdues à séparer les activités

• souvent la connaissance est dupliquée à plusieurs endroits pendant les différentes activités

• Les connaissances peuvent évoluer durant ce processus et engengrer des incohérences

Requires Human dedication

• A pain to update

• Requires special tooling

• Boring manual transcription

Manual transcription

Developer trying to layout code in MS Office

• très souvent, quand il s’agit de documenter, les membres de l’équipent choisissent des éléments de connaissance et les transcrivent manuellement dans un format adapté à l’audience cible

  • En gros on prend la connaissance de ce qui a été fait dans le code et on l’écrit dans un autre document

• refs unknown source

• static

• text in Ms Word

Do we read it?

• No one really reads it cover to cover

• Not easy to engage conversations with

What does it tell us?

• What the system should have been

• When it was written

• Often by a different person