Add actual JSON to the docs.

[seanparsons]

We could do with the JSON itself being parsed listed in some of the documentation pages, as it appears to be less clear to users what they're actually parsing.

[briantopping]

Hi Sean, I'm a new user and spent the last 24 hours getting started with Argonaut. It really is a beautiful library, thanks for the team's hard work on it.

What I wanted to add was some of the things that weren't obvious to me in hope they would provide thought seeds. Sometimes it's hard to remember what was hard. :) It's really just two main items.

The first is a diagram could help a lot. Something like https://github.com/spray/spray-json/blob/master/images/Conversions.png from spray-json maybe. From the existing docs, I was able to muddle out most of the transitions on that graph, but for instance, I could not figure out how to easily transition from Json to a Scala object. These three states and six transitions are keys to getting going.

The next one is kind of something that Argonaut shouldn't have to deal with but could help a lot of folks with is a refresher on implicits and how important they are to Argonaut. Back to the graph, it would be pretty amazing if the graph could show the involvement of implicits in the transitions.

In any event, I was finally able to figure out some great patterns by searching Github for "argonaut downfield" and came up with some code that really made sense. Interestingly, it explained so much of what I was missing from the above. I'm a fan of readable unit tests and while I realize what you guy have done is probably super efficient and complete, it's very hard to use as a reference.

Please let me know what I can do to help! I don't know that I am good enough with the tool set yet to write these kinds of docs, but if I can get my mojo up, maybe I'll even give it a shot! :)

[seanparsons]

@briantopping Do you mean this: http://argonaut.io/doc/codec/

[briantopping]

Hi Sean, I spent a lot of time on the docs, including that page. I'm not sure what reference you are intending to convey there. Maybe my comments aren't relevant.

[seanparsons]

@briantopping I was referring to your comment in the IRC channel mostly.

[briantopping]

@seanparsons I don't have an IRC client with history so I can't look back there. Gitter #ftw :)

[tylerjharden]

I'm going to have to say that even as someone who considers myself extremely familiar with Scala, the countless uses of very custom and cryptic operators really puts me off from understanding this library.

It looks to be an extremely powerful library, and I am putting in consistent time trying to wrap my head around it, but I struggled for 2 hours trying to figure out how to simply read a top-level string field and get it into a Scala primitive String so I can do a value comparison.

None of the documentation really shows how to do this, and unless you read all the docs on argonaut.io and then proceed to one-by-one lookup what method names those crazy operators coorelate to in the Scaladocs, you'd be lost.

I feel like some more general examples would be nice, and not a slew of tests that rely on all this slap-happy syntactic sugar from Scalaz / s2, especially for those of us who aren't familiar with those particular libraries.

[briantopping]

We may not be the target audience for this product. That said, I'll probably keep plodding along. The occasional profane outburst of joy in finding how to do something amazing is rather entertaining, especially when in quiet coffee shops.

[seanparsons]

@tylerjharden In all seriousness please help contribute those sorts of things, even if it's just some snippets that you needed to achieve something.

As with a lot of open source projects there's a fair chunk of spare time consuming effort that it takes to do a lot of things.

[briantopping]

@seanparsons I've never used the wiki, but I wonder if it might be a lightweight manner for folks to contribute unofficial snippets. I also have some stuff to share and maybe it would help you optimize your workflow of the eventual doc?

Contributing to OSS is part psychology as I'm sure you know, every project is as different as their founders and nobody wants to put a lot of time into something subjective like docs and have them languish. Scalaz raises the bar significantly, it's just as likely that mere mortals like us are simply wrong about what they are writing, turning it into a very objective rejection.

WDYT?

[tylerjharden]

@seanparsons @briantopping I didn't mean for my comment to seem rude, I'm just confused. I notice you and some of the other contributors to Argonaut and Scalaz are much more familiar with functional programming as a paradigm in and of itself (with heavy Haskell background). This use of operators is more of a functional pattern I'm simply not used to.

I wouldn't mind contributing what I "discover", and I also wouldn't mind contributing implicits and equivalent helper methods that would make this easier to use for those of us migrating from Java/OO backgrounds to Scala and learning functional as we go, but I am utilizing this library for a production data streaming solution and really have no choice but to experiment and learn it, so I will do what I can, no promises due to time constraints.

[briantopping]

Likewise for my parts of the discussion...

Maybe Argonaut is a great vector to learn the benefits of Scalaz and that team would take an interest to contributing to doc as a primary use case of Scalaz. Seems like everyone would win there.