Add a tutorial and a starting point for users

[melrief]

Hawk is a little complex for new users and I think this is due to the lack of some starting points for our program. We have a nice documentation that explains how Hawk works but I think we should add also a tutorial like this one from IBM on awk. This tutorial should cover basic, medium and advanced practical examples of Hawk for real-world use cases.

I also think the documentation should be split into a starting point document and the documentation itself. In the first one we can introduce Hawk itself and contains what is now in document from the beginning to the modes (introduction, overview and when you should use hawk). In the second one we should just document hawk and how it works (modes, input, output, magic and all the features that hawk has).

The main README.md should then give three pointers, one for the starting point, the second to the documentation and the third one to the tutorial(s). The tutorial(s) and the starting point should have pointers to the documentation for more details.

What do you think?

[gelisam]

I'm already tired of writing documentation :(

Maybe we could instead work on our error messages, so that users can try to use Hawk and manage to get by without having to understand everything?

[melrief]

Don't worry, I think it's my turn to write some documentation :-). I prefer to have a tutorial so I will work on that.

About the error messages: yes, we should improve those also.

[melrief]

I have pushed a new branch called tutorial that contains a tutorial.md file. This is my idea of tutorial, it will be bigger than this and probably it will also cover working on JSON or another format (still to decide). If it grows too much I will split it into files with an index file, but before that day the tutorial will stay on a single markdown file.

If you have time to read it, please go ahead.

[gelisam]

I like it, I think it's quite clear! Of course, I am already familiar with the material, so maybe my judgement in the matter cannot be trusted.

I especially like the highest userid example, because to a haskell user it is very clear that you should be using on, and then you immediately show how you can go ahead and do that.

I would like to tweak a few sentences here and there, but since you still plan to modify it, I should probably wait until you are done. Great work so far!

– Samuel If you are an online service provider, then by sending an email to this address, you have agreed to the following Terms and conditionshttp://gelisam.blogspot.com/p/terms-and-conditions.html .

On Sun, Jan 12, 2014 at 6:29 PM, Mario Pastorelli notifications@github.comwrote:

I have pushed a new branch called tutorialhttps://github.com/gelisam/hawk/tree/tutorialthat contains a tutorial.md file https://github.com/gelisam/hawk/blob/tutorial/doc/tutorial.md. This is my idea of tutorial, it will be bigger than this and probably it will also cover working on JSON or another format (still to decide). If it grows too much I will split it into files with an index file, but before that day the tutorial will stay on a single markdown file.

If you have time to read it, please go ahead.

— Reply to this email directly or view it on GitHubhttps://github.com/gelisam/hawk/issues/78#issuecomment-32138050 .

[dubiouscript]

imho :upside_down_face: something like

https://jiehong.gitlab.io/jq_offline/ or https://jqplay.org/

would be ideal from the perspective of hawk / haskell novice ;)parts of

perhaps including some relevant (drop-down) reference along the lines of
https://learnxinyminutes.com/docs/haskell/

though idk how feasible that may or may not be ...