[simoncion]

This gets a Cowboy application up and running, but it doesn't tell you what to do to write your own Cowboy application, and doesn't give you a very firm understanding of either how the hello_world example works, or how to modify it to suit your needs.

As someone who's been down this road in the past, unless you're already rather familiar with Erlang and OTP's conventions, the gap between the User's Guide and the API documentation is far too large to make connecting information you learn from one with information you learn from the other easy.

I've summarized my personal struggle with the Cowboy user's guide and documentation in my other comment in the thread. Please read that comment before you downvote this one. :)

[plainOldText]

As far as I know there's no such thing as a `Cowboy application`. They're all Erlang/OTP applications. Sure, there's a learning curve associated with OTP apps, but since Erlang is a bit of an exotic language, I think it's understandable.

If you'd like to learn about the concepts behind an OTP application, you can read this guide: http://learnyousomeerlang.com/building-otp-applications or the Erlang documentation for OTP apps (which is pretty good I think).

Another viable option in my opinion would be to just look into the Phoenix framework for the Elixir language. Under the hood it uses cowboy. And it feels a lot like Rails.

[simoncion]

I guess you didn't read my other comment in this thread. Please read it. ;)

> As far as I know there's no such thing as a `Cowboy application`.

From one pedant to another: "I know that." >:)

However, there is (to put it loosely in OTP terms) a set of Cowboy behaviours. Your application is expected to implement one or more of these. While the API for these behaviours is reasonably documented, the Cowboy equivalent of the -say- gen_server "User's Guide" is so sparse as to be almost non-existent.

[plainOldText]

Okay. Read it now! :-)

I think one reasonable strategy of learning how some piece of software works or is meant to be used – especially when documentation is poor – is to just look at the source code (tests included).

I'm just getting started with the Phoenix framework, and I'm learning Elixir at the same time and reading through the source code helps me a lot, because:

    1. I can check out how things are implemented
    2. I get to read some idiomatic Elixir which helps me learn the language better

One can get reasonable understanding of software at the interplay between reading the docs and reading the source code.

[simoncion]

I generally agree that -in the absence of sufficient documentation- reading the tests and source for the project is generally the best way to learn how to use a project.

However. If the language the project is written in is wildly unfamiliar to you, and you've never had experience with a similar language, then this technique is often... less than satisfying.

From your comments, it appears that you have more than a passing familiarity with Erlang/OTP. You have to admit that it would be substantially harder to understand both Elixir and Phoenix without your understanding of Erlang. :)