Développement piloté par le README (2010)

• Développement piloté par le README : une approche qui consiste à rédiger le README en premier lors du développement logiciel
• On entend souvent parler de diverses méthodologies et techniques de développement comme TDD, BDD, Extreme Programming et SCRUM
  • Mais si le logiciel que nous développons ne répond pas aux besoins des utilisateurs, tout cela n’a aucun sens
  • Même une implémentation parfaite ne vaut rien si elle suit une spécification erronée, et une belle bibliothèque non documentée n’a pratiquement aucune valeur
  • Si un logiciel résout le mauvais problème ou que l’on ne sait pas comment l’utiliser, cela entraîne de graves problèmes

Solution : commencer par rédiger le README

• Pourquoi rédiger le README en premier
  • Rédiger d’abord le README, avant le code, les tests ou les user stories
  • La rédaction du README est une étape essentielle pour créer un bon logiciel
  • Tant qu’on n’a pas formulé par écrit ce qu’est le logiciel, il n’est pas clair ce qu’il faut coder
  • Le README permet de réfléchir au projet de manière structurée
• Avantages de l’approche README d’abord :
  • Une occasion de penser le projet de façon structurée :
    • On peut réfléchir au projet de manière structurée sans avoir à modifier le code
    • Avant de coder, on peut se pencher sur la structure du projet et les API qu’il contiendra
  • Une documentation de qualité :
    • On peut rédiger la documentation au début du projet, quand la motivation et l’intérêt sont au plus haut
    • Rédiger le README plus tard est ennuyeux et peut conduire à manquer des détails importants
  • Une meilleure efficacité du travail en équipe :
    • Les autres développeurs de l’équipe peuvent recevoir des informations sur l’interface avant l’achèvement du projet et commencer d’autres tâches avec confiance
    • Travailler sans interface claire peut nécessiter une refonte importante du code
  • Une base concrète pour les discussions :
    • Le simple fait d’écrire en texte la solution proposée permet à chacun de discuter avec une idée claire
• Caractéristiques du README Driven Development (RDD) :
  • Le RDD peut être vu comme un sous-ensemble ou une version limitée du Documentation Driven Development (DDD)
  • Le RDD limite le document de conception à un seul fichier, ce qui évite le problème des spécifications excessives
  • Il encourage à maintenir des bibliothèques petites et modulaires

Conclusion

• Considérer le processus de rédaction du README comme un véritable « acte de création »
• Toutes vos idées brillantes doivent être exprimées dans ce document, qui doit à lui seul constituer une preuve de créativité et de capacité d’expression
• Le README doit être le document le plus important du codebase, et le rédiger en premier est la bonne approche

[princox]

Que ce soit un logiciel, un roman ou un film, ou toute autre forme de création,
j’ai l’impression qu’en concevant et en planifiant sur le papier avant de le réaliser, on peut plus facilement soigner les détails.. :)

[markman]

J’ai oublié l’essentiel pendant tout ce temps, mais il est temps de m’y mettre maintenant.

[halfenif]

Nous avons décidé d’appeler cela la « conception de base ».

[gargoyle92]

D’une certaine manière, cela ressemble sans que je l’aie voulu à ma façon de travailler et au contexte dans lequel je travaille.
J’ai l’impression que cette partie prend la forme d’un "README".

Quand je travaille, j’ai tendance à clarifier le What, le Why, le How, etc., puis à avancer en donnant progressivement une forme aux tâches à accomplir, donc c’est assez similaire.

[kandk]

Développement piloté par le README

[dbs0829]

Comme nous sommes une organisation de recherche, nous réfléchissons beaucoup à la manière de publier les résultats de nos travaux sous forme de code, et je me dis que le développement piloté par le README pourrait très bien nous convenir. Cela me semble être une approche qui vaut la peine d’être envisagée dès le début d’un projet de recherche.

[jamsya]

De même, quand je fais du backend, il m’arrive d’écrire d’abord une ébauche de documentation API en regardant l’interface,
et ça m’a pas mal aidé à réduire les tâtonnements.

[bbulbum]

D’une certaine manière, cela donne l’impression de l’importance qu’il y a à définir d’abord précisément le problème à résoudre.

[xguru]

C’est un article de 2010, mais je l’ai découvert en lisant autre chose, donc je le partage.