Do we need to make READMEs for earlier exercises simpler / add more hints?

[sjwarner-bp]

Some feedback taken from the exercism/java Gitter room:

I'm having trouble even starting the exercism course. I'm on the 2nd exercise and I just have no idea where to begin.

...

I actually managed to get the first two tests to pass now. But yeah in the beginning it's a bit overwhelmingly contextless and I had no idea how to start
That task has a huge README on TDD which is great, really helpful to understand how to work your way through these tasks in general. But at that stage I wasn't ready for the task itself. I needed a nudge in the right direction.

As it was, it turned out I just needed to understand that if I simply deleted the exception and return the string in the test, that the test would pass.

Once I understood what exactly the test was doing and what it was expecting, (and that I needed to return the value rather than print it), I've been pretty much fine ever since.

Maybe we need to append some hints to make it more obvious what is expected for brand new users (or make it more explicit that the tests are the place to consult for implementation questions?

What do we think @exercism/java? I'd be interested in hearing opinions and getting them implemented if we decide anything needs to be done! 🙂

[FridaTveit]

That's really useful to know, thanks @sjwarner-bp! 🙂

The first exercise, hello-world, has a long tutorial which I think explains everything you have to do to make the tests pass (including deleting the exception and returning something instead). We could add that tutorial to more of the earlier exercises? Or maybe just reference it in the other exercises so that people know where to look for more instructions?

[sjwarner-bp]

That's perfect! It's been so long since I did the track, I'd forgotten that was there.

I don't want to bloat the readmes unnecessarily because I think we shouldn't overwhelm users with too much info! Additionally, it was mentioned...

That task has a huge README on TDD

... so we probably shouldn't add too much! I like the idea of referencing the tutorial 🙂

[FridaTveit]

Okay, should we reference the tutorial in e.g. the first three core exercises? Or all exercises with difficulty 2 or below? Or any other suggestions? 🙂

[FridaTveit]

What do you think @sjwarner-bp? I think maybe referencing the tutorial in all exercises with difficulty 2 or below would be best? That's five exercises (I think, unless I counted wrong) which sounds like a good number. And it hopefully shouldn't be too hard to remember to add a reference to any new exercises that are added. We can mention it in the new exercise section of the contributing guide 🙂 And I think most exercises that are added tend to have a difficulty higher than two anyway, so I don't think it'll be a very common problem 🙂

If you're happy with that approach then I can make good first patch issues for adding the references 🙂

[sjwarner-bp]

Oops! Completely missed this message - I think that sounds good too 🙂

Hopefully that will help new users out (and adding it to the contributing guide is a great idea)!

[FridaTveit]

All the issues are closed now so I believe this can be closed too! 🙂