Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Readme Driven Development

tom.preston-werner.com

Post reply on HN
Print view View original

31–40 of 59 posts

Re: Readme Driven Development

#31

Post by benbjohnson »

I would love to see some way to relate test cases with sections of the README. That way you could see code coverage of your README. It's difficult to retroactively write a README after you've written your code but it can also be difficult to write all the code described by your README.

The README shouldn't hold every detail of your implementation but it would be a good starting point for developers trying to find where described functionality is located in a library.

Also, it would provide the inverse: You can see what test cases you have that are not described in your documentation.

Re: Readme Driven Development

#32

Post by stonemetal »

raggi wrote: post #30
vcr2 wrote: post #4

It would be nice, if we dont consider the fact that nobody reads README at all. "A perfect implementation of the wrong specification is worthless." The point of BDD is exactly this: bring specification to the scene, give it a first class citizen status, it becomes a live entity in the system, more influential than before. I don't believe Readme or any other document can be as influential as a Cucumber feature, for in…

show me a christian that grok'd the entire bible before calling themselves a christian, and i'll show you a developer who reads the entire behavioral specification of a library before using it. your idea works for libraries that are small, it's appalling for libraries of any significant size. the point of a readme is to provide a useful summary that is quick to start using for the critical path use cases. if you look…

>>your idea works for libraries that are small, it's appalling for libraries of any significant size.

Really could you see a developer reading the entire .net or java standard library test suite before using either Java or C#

Re: Readme Driven Development

#33

Post by grandalf »

I think one big strength of RDoc over other documentation formats is that it gives the README a fairly prominent place. Seeing a few usage examples, high level thoughts makes using a new library so much easier.

Re: Readme Driven Development

#34

Post by tjpick »

Seems like we're just talking about writing a spec before the code, and README being a specific form/template/symbol for that. Starting to feel like we're moving full circle w.r.t. agile vs process/documentation heavy methodologies.

Re: Readme Driven Development

#36

Post by joe_the_user »

tjpick wrote: post #34

Seems like we're just talking about writing a spec before the code, and README being a specific form/template/symbol for that. Starting to feel like we're moving full circle w.r.t. agile vs process/documentation heavy methodologies.

Well yeah...

You could pretty well describe the software methodologies of the last twenty years as being over-generalizations of basically good ideas. Once a given reasonable idea has pushed beyond its usefulness, the opposite good idea appears and ... is pushed beyond its usefulness.

Tossing out understanding and just having tests and code can easily result in disaster in many cases (compilers, sudoku solvers, etc) while over-designing can result in the opposite disaster in other cases.

Re: Readme Driven Development

#38

Post by steveklabnik »

raggi wrote: post #29
integraleq wrote: post #23

this is an excellent post and quite relevant. i have found this kind of epiphany as well while writing a python based framework at my company. i would extend the README driven approach to even suggest a developer blog driven design methodology, since it allows for a more dynamic way to clarify points and also add diary entries for 'thinking aloud' while you are building complicated libraries.

no. blogs are not a substitute for documentation. ruby has been suffering this for too long. blogs have several problems: - they don't get updated - they don't get patched - they don't ship with the software - they break when the user dies / moves / leaves / changes software - they have a lower signal to noise ratio

- they accumulate Google juice over time, overpowering advice for newer versions of your framework.

Re: Readme Driven Development

#39

Post by joelhaasnoot »

Ah yes, does anybody else remember the glory days of shareware and freeware dominating, sold on magazine CDs and various collections? The good software always had an excellent, beautifully crafted readme, detailing features, install how-to, changelog, and other wonderful details! No need for google! Sometimes we forget there are people that operate without internet for documentation...

Re: Readme Driven Development

#40

Post by _mql »

So true! I've also discovered for myself that keeping a one-page document, serving as red thread makes everything so much easier.

However at some point I wasn't satisfied with the options a regular REAMDE offers. I wanted to write such a document in a declarative style and eliminate the limitation of having just HTML as an output format. Luckily a friend of mine is working on a parser that reads markup (using as much natural language as possibe, inspired by Markdown et. al) and turns it into a data representation (JSON) rather than pre-rendered HTML.

Straight talking: I'm using it for documenting Unveil.js (http://github.com/michael/unveil), a graphic library sitting on top of HTML5 Canvas. It just turns this (http://github.com/michael/unveil/blob/master/index.ndg) into this (http://docs.quasipartikel.at/documents/unveil). The goal is to use it for on-the-fly documentation generation (along with sourcecode, or for regular documents), without the need for statically rendered HTML files.

Here's the (on-the-fly) rendered version: http://docs.quasipartikel.at/#/unveil

It's all at an early stage, but I'd love to have some discussion about such data-driven documentation. :)

-- Michael

Post reply on HN