> Never use a *long word* where a *short* one will do. — George Orwell @@@ > *Simple*DocumentationGenerator UsingJSPAndACoupleOfOtherStuff*.jar* — Senior Java Developer
![](../../img/avatar.jpg)
## *Thomas* Parisot [thom4.net](https://thom4.net) – [@thom4parisot](https://twitter.com/thom4parisot) @@@ ![Pardon my French](../../images/pardon-my-french.jpg) @@@ ![Full Stack JavaScript](../../images/javascript.png) @@@ ## BBC R&D [github.com/bbcrd](https://github.com/bbcrd) [bbc.co.uk/rd](http://bbc.co.uk/rd) @@@ ![I published](../../images/npm.png) [npmjs.org/~thom4](https://npmjs.org/~thom4) @@@ [![Sud Web](../../images/sudweb.png)](http://sudweb.fr)
# README ## Driven Development 31st March 2014 — [Write the Docs EU](http://conf.writethedocs.org/eu/2014/) @@@ @@@ @@@ @@@ @@@
# Back to reality Or how I figured out the usual *complexity* of things. @@@ @@@ @@@ @@@ @@@
# State of *2011* @@@ # Paris Web To converse = to speak + to listen. @@@ # Startup 4 developers, *trust* et remote working. @@@ # Striving for *simplicity* ~~Specifications~~, sprints and coffee machine. @@@ # Choosing the *tools* GitHub, JavaScript and `npm install`. @@@ # {1, *5*} *projects* @@@ ## How do you *install* it? @@@ ## How can I *update* it already? @@@ ## What is the command line to *run the tests*? @@@ # #wanted ## Better *documentation*. Reward is obviously a bottle of wine
# Paradox Or how we easily waste our *efforts*. @@@ # *Time* invested to create. @@@ # Pleasure to create *useful* software. @@@ # Satisfaction *to share* our work and findings. @@@
# README ## ------ ----------- @@@ # Evidence *First* file displayed on GitHub. @@@ # Simple Markup `#` + `*` + `**` + `!` + `[]()`
Markdown, RST, AsciiDoc etc. @@@ # Fast to *learn*, to *write* and to *read*. @@@ # Pervasive HTML, PDF, JSON, text file *etc*. cf. [pandoc](http://johnmacfarlane.net/pandoc/). @@@ # In a *nutshell* Who, what, when, where, why and how. @@@ # Freedom To consume and to contribute. @@@ # Alongside The versioned code. @@@ # *Examples* To provide context. @@@ # *Shallow* limits Trust your gut feelings. @@@ # Content First *Technicity* stays back.
# README ## *Driven* ----------- @@@ ## What do you *mean*? @@@ ## It's not only about *existing* projects. @@@ ## It's about *ideas* and *new* projects. @@@ # *Before* writing code. @@@ # Crystal *clear* With ourself, our team and contributors. @@@ # *Designing* code. @@@ # Collecting *feedbacks* Fix the bugs *before* writing code. @@@ # Code *sketching* Fast, straight to the point and *easy*.
# README ## Driven *Development* @@@ ## From *text*… @@@ ## … to *code*. @@@ # *Complexity* detection Time to break your code. @@@ @@@ @@@ @@@ # Pull Requests [Better to split 'em](https://thom4.net/2013/the-55-commits-syndrome/). @@@ ## Issue the *intention* @@@ ## Request for *validation* @@@ ## Implement on *agreement* @@@ ## Eventually *someone else* will do it @@@ ## [mdlint](https://github.com/ChrisWren/mdlint) Validates code in Markdown files. @@@ ## [README Tree](https://github.com/DTrejo/readmetree)
# *Wrap*ping up @@@ # Single *entrypoint* `README.md` @@@ # Shared *vision* You + people. @@@ # Explicit *intentions* 6W. @@@ # Easier *dialogue* Because part of the process. @@@ # Faster *time to code* (with better quality). @@@ # *Simple* If not, there is a problem.
# That's it! @@@ # Credits * https://xkcd.com/927/ * [Thanh](http://clients.tranches-de-vie.com/index.php/2011/paris-web-2011/1015-ateliers/img-0275) @@@ # Resources * They coined the concept: * [Tom Preston-Werner](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) * [Mark Rickerby](http://www.slideshare.net/maetl/readme-driven-development-12783652) * Softwares * [specdown](https://github.com/moonmaster9000/specdown) * [readmetree](https://github.com/DTrejo/readmetree)