Moshi: Impossible to use with Kotlin

[Pilvinen]

As a beginner Kotlin student and first time Moshi user I find it impossibly difficult to get Moshi working with Kotlin after 8 hours of strenuous trying and failing.

I want to give some feedback about my experiences as someone new who has jumped right in and doesn't necessarily know or understand everything yet. Please have some patience and understanding.

All I can say is it shouldn't be this difficult. The Java examples seem rather straightforward in comparison and I feel like if I tried I might get those working with relative ease.

I tried to get working a simple "read JSON from a file, turn JSON into Kotlin variables", but I couldn't.

Rather than focusing on what code I've been running - which would be helpful only in this one case - I'd rather like turn your attention to the documentation, which is - or should be - the foundation of any project.

1) Some required Moshi Gradle dependencies are listed in a very poor manner in the docs. When you want to get started quickly, get your environment set up and CTRL+F the docs to search for "Gradle" you'll jump straight into the section titled vaguely as "Gradle", but then you've already skipped past some critical parts about reflection and codegen dependencies, some of which are not even referred to as being Gradle/Maven dependencies. If that section of the docs were rearranged a bit and cleaned up it would make for a much smoother experience.

2) Simply linking to Java docs is not enough. Good documentation always includes examples, tutorials, etc. Please read this excellent article on the subject: https://www.divio.com/blog/documentation/

3) Due the lack of examples in the docs I turned to Google. None of the third party examples I could find after couple of hours of googling and testing seem to work - at least not "out of the box". The docs absolutely need at least one, from start to finish, working example (preferably several for different use cases). The examples should be as simple as possible to cater for newbies and they should be complete examples in their own right (preferably with comments) that work straight away with a simple copy paste job. This way it would be very easy to get into it and start experimenting and learning more. It would also ensure the user that nothing is wrong with the Gradle setup or anything else. "If the example doesn't work -> you've got something set up incorrectly."

As final words - you are the experts, you already know this stuff and you develop this stuff, so it's easy for you. Please show your amazing skills by making us equally amazing documentation which helps adoption. It would be really helpful for beginners like me.

Thanks for reading my feedback.

[swankjesse]

Wanna help?

[Pilvinen]

That's very kind of you.

I finally got one example working. It's proven quite useful in shining some light on the rest, even though I'm still figuring things out.

But I think the best way you could help would be simply to work on the documentation - when you have a good free moment.

Thanks!

[swankjesse]

Wanna help? Maybe write a Medium post or something that you would have liked to have read?

[brianPlummer]

@Pilvinen hey there! i wrote a medium post a little while back that is somewhat relevant here: https://medium.com/s23nyc-tech/data-model-as-your-table-stakes-6937c95e7039 . I understand that it may not be exactly what you need, however, it may point you in a good direction.

[Pilvinen]

Thank you, Brian. I didn't come across your post via Googling. It's proven very helpful for understanding the whole process.

[the-sauce]

Hey guys;
I got moshi to somewhat do what I wanted, but I can confirm that it was hard.
A wise next step for making this library more popular might be providing a better documentation and/or a list of useful links.

[swankjesse]

No further action to take on this.