Better Docs about shapeless

[milessabin]

Thanks for the comment. Assuming you've looked at the existing documentation on the wiki and the scaladoc, are there any specific areas you'd like to see addressed?

[sirinath]

Something like a tutorial series and how tos based on topic areas. This would benefit all the type level projects and documentation and examples are very thin. Also perhaps some video tutorials and lectures.

[sirinath]

I think a good starting point would be a good user guide. Followed by something like : http://learnyousomeerlang.com/, http://learnyouahaskell.com/ covering the whole typelevel stack and perhaps some related projects.

[milessabin]

I'm going to close this for now.

Better documentation is always a good thing: which is really the problem with this ticket ... given that there's always room for improvement it's completely unclear how it could ever be closed as fixed. A ticket that lingers on for months without any clear resolution doesn't do anyone any good.

I would welcome (multiple) very specifically targeted tickets relating to documentation, along with clear criteria for what counts as success. Ideally these would be small enough that one person would have a reasonable chance of completing one of them with no more than an hour or so's worth of effort, preferably less. This might be something along the lines of "Add a paragraph to the wiki on . ."

Obviously if there were pull requests attached to such tickets then that would be even better :-)

Nb. this issue tracker is for shapeless, not Typelevel in general, so whilst more documentation would be highly desirable for all of the Typelevel projects, this isn't the right place to ask for anything other than documentation for shapeless.

[sirinath]

I think it is best is that as time permits you could add wiki pages with basic info and tutorial. No need to open new issues I guess.

[aloiscochard]

@sirinath is there some specific tutorial you have in mind? like let say some specific you were trying to do and was not able to find explanation?

[sirinath]

I let you best decide how to tackle this. Let me relate my experience when I tried to get my hands dirty on Shapeless. I initially watched the videos on Shapeless and then tried my hands on shapeless. There was a definitely a big gap between what was available and the tutorials I had watched. I opened this issue mainly to see material towards closing this gap. The result was I was afraid to take things further fearing if I get struck I might not be able to take things further as where I live there hardly any Scala developers let alone anybody using Shapeless who I could ask about the issues thus I would solely have to rely on documentations.

At this point I do not know the extend on what is missing but just feel there is a big gap regarding the power Shapeless provides vs what is glossed over in videos that on the subject. I feel the same about the other type level projects. Again I do not know where the gap lies and the extent of the gap. Also exploratory / heuristic learning takes a lot of time.

There is a gap between the material out there (lesser extend Scalaz) and implementation. Fear of getting struck and not always having the support keeps you away from using this for anything serious.

[travisbrown]

@sirinath, I agree that more Shapeless tutorials would be great, but in the meantime I'd encourage you to ask any specific questions you have on Stack Overflow. I think we do a pretty good job of answering questions there quickly, and we often mine material from there to add to the project examples.

[aloiscochard]

@sirinath I would just add that IRC is actually an amazing resources when it comes to real time support...

You'll find @milessabin in the #shapeless room, and lot of other folks ready to help! You should take a look at the #scalaz room too :-)

See you there!

[sirinath]

Thanks for the support. Just logged in.

[sirinath]

I am not a heavy user of chat so not I might be wrong on this but if the main source of knowledge is chats and forums one thing I fear by this approach is much of the knowledge becoming sort of fork law. It has seem to have worked so far to many of the community through. At least forums are better as you get a historic record (which also is in place). But the best thing for me is a nice A to Z tutorial.