I don't like gherkin. I think that it has awkward syntax, it lacks type safety, it's very verbose and doesn't have enough ability to abstract scenarios. Rather than being a source for generating the documentation it tries to be the documentation.

Nonetheless, there is a small number of projects where they either work around these constraints or it doesn't matter as much, so it can work. I find that most people that apply gherkin to their projects run into a brick wall though - usually for one of the above reasons.

I built https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity and the ability to abstract scenarios.

It is explicitly designed as a source for generating markdown documentation so that you can create richer docs like https://github.com/hitchdev/hitchstory/blob/master/examples/... for your users rather than more test-like documents like https://github.com/diaspora/diaspora/blob/develop/features/m...