A Better Way to Code: Documentation Driven Development

1. clitest

   1 1 164 - 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

2. Stream

   getstream.io featured

   Stream - Scalable APIs for Chat, Feeds, Moderation, & Video. Stream helps developers build engaging apps that scale to millions with performant and flexible Chat, Feeds, Moderation, and Video APIs and SDKs powered by a global edge network and enterprise-grade infrastructure.

   

3. sequencer

   2 6 67 9.0 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.

4. hitchstory

   3 28 101 8.5 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