Rewrite tutorial with "how do I do X" in mind

[domenkozar]

For example, there's an Alternative section.

Alternative is a "what", instead of users are interested into "how" and potentially "why" when looking at sections. The body of the section should then describe the "what".

There are stackoverflow questions to confirm that - I've spend non-trivial amount of time as well to figure this out.

[HuwCampbell]

I think that this is one where people have different feelings. I quite like the current structure, and don't particularly want to invert the flow.

That said, our current running examples are pretty bad, and should probable include some of the more standard combinators people use.

[domenkozar]

I think that this is one where people have different feelings. I quite like the current structure, and don't particularly want to invert the flow.

Can you explain a bit more behind that thinking? The title could even include both for targeting different audiences.

[HuwCampbell]

Maybe I have misinterpreted what you're suggesting, but I like that the current structure is designed to be read beginning to end coherently; and focuses on simple things, then composition, then details. Framing as a "How" pushes one more towards a question and answer style instead of prose.

I'll have a think about how to make things more discoverable.

[PI-Victor]

i think that, instead of re-writing or changing the main examples in the readme, an examples dir with actual real world examples would be very useful. And just point to the dir in the main readme.

the example(s) could just highlight the main features.
e.g.

prog
 |--> customized parserInfo (version, about, author, etc)
 |--> globals
 |--> command
        |--> flag
 |--> command
        |--> file argument
|--> command
       |--> argument
              |--> default value
...

I've been struggling for months with haskell, which is no way this libs fault but my limited knowledge of haskell, and i can't seem to find some relevant real world examples that are not too complex for a total noob to understand right away.