3 ms·

The docs (or lack there of) were the reason I stopped playing with Phoenix and Liveview. As an Elixir n00b, source diving to figure out how things work isn't an

The docs (or lack there of) were the reason I stopped playing with Phoenix and Liveview. As an Elixir n00b, source diving to figure out how things work isn't an option for me right now. I'm sure you've been linked these a thousand times, but the docs for Laravel are imo, the gold standard for developer documentation. I love the idea of Hex being a built in solution for documentation, but a hodgepodge short guides supplemented by the Hex docs isn't enough. I also realize you're not Chris, but I figured it was worth mentioning. I do really like Elixir and hope I can come back to it when these ideas mature a little more!

rkangel 4y ago
I'm incredibly surprised by this. I personally use the Phoenix documentation as the gold standard for good developer documentation! There is an excellent, clear and practical set of guides that take you through the increasing complexity of a Phoenix app. I find them very clear, and surprisingly complete. They start here: https://hexdocs.pm/phoenix/up_and_running.html https://hexdocs.pm/phoenix/up_and_running.html The 'reference level' documentation is also excellent. I picked this example randomly, but it has an extensive guide at the top and then good description of each of the functions: https://hexdocs.pm/phoenix/Phoenix.Channel.html https://hexdocs.pm/phoenix/Phoenix.Channel.html
- stanmancan 4y ago
  I think what Phoenix is missing is a way to search all of the included packages from one place. The one thing I struggle with is having to figure out what module a function is in so I can find the docs for it. As a Developer I don’t necessarily think I should have to bounce around between docs for Phoenix, Phoenix.HTML, Phoenix.PubSub etc. The docs can be separate for sure but at least give me a single central search for them.
  - josevalim 4y ago
    I agree this is a pain and we have an open issue in ExDoc (#1551) to tackle this. If anyone is interested in submitting a PR, it will be very appreciated!
    - yurishimo 4y ago
      Thanks Jose! I know writing docs/guides is really hard and 1st class search can make a huge difference. Another thing I love about the Laravel docs, is searching via a keyword that I know may exist on a specific page; the list of available methods on a `Collection` is one I use all of the time. I see in the Github issue you specifically call out _not_ searching text content from related modules, but I think if you can make it performant, it's worth the extra effort to allow full text search. I suppose the harder part might be ranking if you're not using a system that is built for that use case, but I think it would be helpful.
sfusato 4y ago
I've made the switch from PHP/Laravel to Elixir/Phoenix and I've found the documentation in Elixir land far more superior and complete. I've yet to find something better anywhere else. What's the equivalent of Hexdocs in PHP land?
- yurishimo 4y ago
  The docs themselves are fine, but when I'm building an app and focused on using the tools available by the framework, I had trouble finding what I needed. Perhaps it was even discovery of not knowing what I needed to even look for. I might know a concept under a different name for example. I don't expect anyone to cater to my exact needs, but I want to find everything in the same place. Someone else left a sibling comment talking about the documentation for different modules not being colocated (Phoenix.PubSub vs Phoenix.HTML, etc) and maybe that was my issue. If literally every module is new to me, that could be a lot of jumping back and forth just to try and reason about what a couple of Plug modules are doing. Granted, it's been at least 6 months since I've tried to play with Elixir and Phoenix so maybe I'll have some time to try again over the holidays. To go back to your original point though, yes Hexdocs is a great tool and the ecosystem encourages documentation, but maybe in this case I'm looking for a more curated guide and I should have been explicit rather than lump it all under "docs".
- conradfr 4y ago
  I don't know about Laravel but I think the Symfony documentation has more practical and extensive documentation and guides (the framework does way more than Phoenix so there's probably a correlation there). There's no equivalent to Hexdocs in PPH land but I think the PHP documentation itself is quite good, once again by usually providing examples for all types/arguments variation for every functions, which the Elixir std lib does not (the REPL allows you to quickly try things though).

rkangel 4y ago

I'm incredibly surprised by this. I personally use the Phoenix documentation as the gold standard for good developer documentation! There is an excellent, clear and practical set of guides that take you through the increasing complexity of a Phoenix app. I find them very clear, and surprisingly complete. They start here: https://hexdocs.pm/phoenix/up_and_running.html https://hexdocs.pm/phoenix/up_and_running.html The 'reference level' documentation is also excellent. I picked this example randomly, but it has an extensive guide at the top and then good description of each of the functions: https://hexdocs.pm/phoenix/Phoenix.Channel.html https://hexdocs.pm/phoenix/Phoenix.Channel.html

stanmancan 4y ago
I think what Phoenix is missing is a way to search all of the included packages from one place. The one thing I struggle with is having to figure out what module a function is in so I can find the docs for it. As a Developer I don’t necessarily think I should have to bounce around between docs for Phoenix, Phoenix.HTML, Phoenix.PubSub etc. The docs can be separate for sure but at least give me a single central search for them.
- josevalim 4y ago
  I agree this is a pain and we have an open issue in ExDoc (#1551) to tackle this. If anyone is interested in submitting a PR, it will be very appreciated!
  - yurishimo 4y ago
    Thanks Jose! I know writing docs/guides is really hard and 1st class search can make a huge difference. Another thing I love about the Laravel docs, is searching via a keyword that I know may exist on a specific page; the list of available methods on a `Collection` is one I use all of the time. I see in the Github issue you specifically call out _not_ searching text content from related modules, but I think if you can make it performant, it's worth the extra effort to allow full text search. I suppose the harder part might be ranking if you're not using a system that is built for that use case, but I think it would be helpful.

sfusato 4y ago

I've made the switch from PHP/Laravel to Elixir/Phoenix and I've found the documentation in Elixir land far more superior and complete. I've yet to find something better anywhere else. What's the equivalent of Hexdocs in PHP land?

yurishimo 4y ago
The docs themselves are fine, but when I'm building an app and focused on using the tools available by the framework, I had trouble finding what I needed. Perhaps it was even discovery of not knowing what I needed to even look for. I might know a concept under a different name for example. I don't expect anyone to cater to my exact needs, but I want to find everything in the same place. Someone else left a sibling comment talking about the documentation for different modules not being colocated (Phoenix.PubSub vs Phoenix.HTML, etc) and maybe that was my issue. If literally every module is new to me, that could be a lot of jumping back and forth just to try and reason about what a couple of Plug modules are doing. Granted, it's been at least 6 months since I've tried to play with Elixir and Phoenix so maybe I'll have some time to try again over the holidays. To go back to your original point though, yes Hexdocs is a great tool and the ecosystem encourages documentation, but maybe in this case I'm looking for a more curated guide and I should have been explicit rather than lump it all under "docs".
conradfr 4y ago
I don't know about Laravel but I think the Symfony documentation has more practical and extensive documentation and guides (the framework does way more than Phoenix so there's probably a correlation there). There's no equivalent to Hexdocs in PPH land but I think the PHP documentation itself is quite good, once again by usually providing examples for all types/arguments variation for every functions, which the Elixir std lib does not (the REPL allows you to quickly try things though).