A Better Way to Code: Documentation Driven Development

• clitest

  1 139 - Shell

  Command Line Tester

  This discussion reminds me of literate programming. An old idea for a more civilized age.

  It also reminds me of clitest[1] (very similar name to the author's lib, but it is another thing).

  You can write examples with prose in markdown, then let clitest verify them for you as if they were tests. Best of both worlds.

  [1] https://github.com/aureliojargas/clitest

• Scout Monitoring

  www.scoutapm.com featured

  Free Django app performance insights with Scout Monitoring. Get Scout setup in minutes, and let us sweat the small stuff. A couple lines in settings.py is all you need to start monitoring your apps. Sign up for our free tier today.

  

• sequencer

  2 19 3.6 Go

  I really love this idea in theory, and I believe that for some system, specially mature ones, it may work well. I see good documentation as a super power; it empowers readers and motivate people to understand more about the system without being caught in the weeds of reading the source.

  The source has baggages, and the intent of every single function calls is not always evident. Writing documentation up-front can help direct the source, but this is a tug-of-war environment. Each affect the other in its own ways.

  And for that reason, documentation driven development can be a real drag. You start writing documentation with the best intentions, everything works great for this first release. But 2 months down the road you need to modify something and it has a ripple effect on many of the things you documented. It's a non-negligible cost.

  I've been working on this open-source tool(https://github.com/pier-oliviert/sequencer) and I've spent a lot of time on the documentation. And what I described above happened. I wanted to make a not-too-big change, and it required me to rewrite 30% of the documentation. I still love the documentation aspect of it, but it definitively has a cost.

• hitchstory

  24 86 8.7 Python

  Type-safe YAML integration tests. Tests that write your docs. Tests that rewrite themselves.

  

  I built a Python/YAML framework around the ability to build these tests and then generate documentation from them. E.g.

  https://github.com/hitchdev/hitchstory/blob/master/examples%...

  which generates

  https://github.com/hitchdev/hitchstory/blob/master/examples%...

  When you show this stuff to other people and gather feedback - that's essentially what BDD is, too.

Suggest a related project