README: Start with a brief 'why' paragraph

[holyjak]

Hi! I have already looked at devcards for the 2nd time and I still fail to understand its value proposition (no, I am likely not in my brightest state :)). Why and when would I use it? What does it give me that figwheel does not?

I think it would really help to start the README not with the "what" of Devcards ("interactive visual REPL") but its "why" (and the use case for it, i.e. when). What problem is it solving? The current start is:

Devcards aims to provide ClojureScript developers with an interactive visual REPL. Devcards makes it simple to interactively surface code examples that have a visual aspect into a browser interface.

What is an "interactive visual REPL"? How does it differ from having figwheel connected to the browser and trying my (visual) Om components (interactively) as I develop them?

Good luck!

[holyjak]

Is it the case that devcards not only displays a React component but also makes it possible to change its props and observe the current state and props (just like React Dev Tools can do for normal react components (though they don't support changing them?) and also rewind to previous setting to observe how it changed over time? Is that the main feature? So is the "why" a better visibility into the current state + increased interactivity through history replay?

[bhauman]

The README could be better.

But like figwheel, this can't be evaluated from an armchair, it is a fundamentally different development experience. Many folks tried and continue to try to evaluate what live dev is like without actually doing it. Its not possible. The only reason Figwheel spread was from word of mouth. One dev to another attesting that it works.

Devcards is hard to describe. And unfortunately I'm a programmer not a communicator ... I have to work 100x harder on communication compared to programming.

Devcards frees you from constraint of developing against the main application and lets you enumerate your components and work on them live in many different states at once, and then keep the resulting document as an environment that you can continue work on in the future. It's a visual lab space and workbench much like a repl. It offers the opportunity to save your lab space and work in it at a later date.

The document produced is similar to a UI kitchen sink, css style guide, and possibly literate code.

Thus one can use the resulting documents to validate how the various components of an application are functioning (in different states) fairly easily. Developers can use these documents as a guide to how the code is intended to be used and also as a place to create interactive code examples to demonstrate failing code, etc..

That description still doesn't capture it.

I'm working hard on my Strange Loop talk to try and get this value prop across and in the end it's turning out that demos that help people experience and see it, seems to be the way to go.

You can really help me out here and give it a try. The new version is very different from the previous version, it "actually works"(TM) and it takes very little to get started as its built in to figwheel.

Just try writing some cljs.tests in it. After a giving it a fair try let me know what you think I should add to the readme to get the experience across to folks.

[pkobrien]

I felt the same way. I look at Devcards a couple of times and tried to understand the documentation and I just didn't get it. Then recently I decided to really "go for it" by doing a git clone of the project and running it on my machine and going through the example cards. Once I did that I was sold. Devcards are awesome!

I don't really have the energy right now but I'll try to work on this issue soon and see if I can write some illuminating devcards. In the mean time, one way to look at devcards is as a super easy to use html harness for the development of cljs code that makes it easy to create a document that includes markdown, actual running code, unit tests, and more. And it has support for React/OM/Reagent.

You can create devcards as an adjunct to your normal development, as tutorials, as a way to poke around in some library that was new to you, as a sketchpad for fleshing out new ideas, etc.

Like Bruce said, though, using it yourself is way better than trying to understand what gets written about it.

[holyjak]

Thanks @pkobrien for sharing your experience! I will follow your lead and just give it a try then.

@bhauman Ok I will try it out and come back with improvements to the README :-) May be the README could start with a (fake) quote similar to

Devcards give you a fundamentally different development experience that can only be grasped when you experience it for yourself. It is a whole new level of productivity, compared to just Figwheel.

This should be both motivating and it conveys that reading the rest of the document does not really help to understand Devcards :)

[pkobrien]

@jakubholynet Welcome to the wonderful world of Devcards. :-)

I created a #devcards channel on Slack: https://clojurians.slack.com/messages/devcards/

Feel free to discuss any devcard issues there as well.

[bhauman]

@jakubholynet I really have to come around and say you are absolutely right about this. I'm still working on my talk for Strange Loop and it is very apparent that I'm not providing enough of a justification for Devcards in the README.

[bhauman]

@jakubholynet @pkobrien https://github.com/bhauman/devcards#why