Upgrade to Pro — share decks privately, control downloads, hide ads and more …

(kick-ass) Readme Driven Development

(kick-ass) Readme Driven Development

as presented at DevFest Vienna 2014. Accompanying blog post will follow.


Floor Drees

October 18, 2014

More Decks by Floor Drees

Other Decks in Programming


  1. kick-ass Documentation Driven Development @floordrees

  2. kick-ass Documentation Driven Development although really we will be talking

    about RDD @floordrees
  3. readme documentation

  4. None
  5. None
  6. None
  7. back to the topic

  8. We often only start writing documentation for our apps and

    app functionality after we have developed them.
  9. a vital part in the decision making process

  10. coding ALL the rubies

  11. nobody puts baby in a corner

  12. Readme or Documentation Driven Development brings back the design-driven way

    of thinking
  13. what about BDD as Behaviour or Business Driven Development?

  14. tl;dr

  15. detecting complexity early on

  16. pro tip:! write your issues like documentation

  17. Until you've written about your software, you have no idea

    what you’re doing.
  18. A perfect implementation of the wrong specification is worthless. A

    beautifully crafted library with no documentation is also damn near worthless.
 Tom Preston Werner
  19. benefits of RDD

  20. think through the project without the overhead of having to

    change code every time you change your mind
  21. you'll have a very nice piece of reference for what

    will become your documentation
  22. pro tip:! keep your Readme open at all times

  23. Retroactively writing a Readme is an absolute drag.

  24. your co-workers can confidently ! start work on other projects

    that will interface with your code
  25. free bonus feature:! no teams just sitting there, being pretty

  26. it's a lot simpler to have a discussion based on

    something written down
  27. It has the ability to give a high level view

    of your code with the goal to gather insight and recommendations from your consumers early and throughout the design process.
  28. it’s markdown! you know markdown! you can do markdown

  29. Github showcases the Readme on the main project page

  30. it’s totally Open Source compatible

  31. pro tip:! Looking to add RDD / DDD to your

    existing project? It can be as simple as just adding a step to your BDD or TDD
  32. pro tip:! make writing or updating documentation ! a required

    first step of your ! development process
  33. pro tip:! include documentation changes as part of your code

  34. pitfalls of RDD

  35. just an over-generalization 
 of a good idea!

  36. have the Readme present what you are aiming for, rather

    than what the code actually does
  37. a Readme does not substitute ! proper documentation

  38. what makes a good Readme?

  39. airbnb for cats

  40. formatting is key

  41. rrrrr code samples

  42. community and licensing details

  43. air your dirty laundry in public

  44. OMG badges

  45. Readmore:
 http://collectiveidea.com/blog/archives/2014/04/21/on-documentation- driven-development/!

  46. thank you @floordrees