Hacker News Reader

Comment by josevalim | Hacker News Reader

I am sorry that this has been your experience.

I am obviously biased but I would stick around. :) I assume you started with LiveView early on, which means the documentation was sprouting and best practices still evolving.

Nowadays it is still pre-1.0 but much closer to its vision, so you should find better docs on the current practices. We now support components too, which declare each attribute, alongside their docs and types. So assuming you go through the update, I am hoping you will have a good time once it is done. And don’t hesitate to reach out in ElixirForum.com if you have questions.

Regarding types, we are researching types for Elixir: https://elixir-lang.org/blog/2022/10/05/my-future-with-elixi... - this is still years ahead, but I thought I would mention in context.

View on HN

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!

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

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

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.

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!

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.

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?

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).

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".

Thanks for the reply. I go through great days with Elixir/Phoenix and bad days, yesterday happened to be a bad day.

I really like the promise of Phoenix, it really is one of the most forward thinking projects I have come across - hence continuing using it, though I don't have all the time in the world to invest in it so just jumping in and out can be painful.

Want this project to work though, I have tried commercial products, IOS apps, and nothing matches upto my vision or indeed my old working prototype.

Reply on news.ycombinator.com