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.

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?

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

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

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.

> Phoenix also feels a little bit magical in the way Rails is

I've felt this about every backend web framework I've encountered, Django included. There's a tension between reducing boiler-plate, and not having directory structures/symbol names/etc. have some implicit order to them. If you want explicitness, don't use a framework and maybe use something like Flask/Werkzeug

> I miss types

Most frameworks have typespecs defined which are enforced by dialyzer, using a much richer type system than most. e.g. Without creating some explicit enum you can make a function signature like:

@spec some_function() :: {:error, :bad_args | :out_of_bounds } | {:ok, SomeStruct.t}

And then you can a caller can just pattern match on that with a 'case' statement, and dialyzer will complain if all paths aren't handled.

> I miss C# and Typescripts documentation

hexdocs.pm is pretty amazing. Elixir as a language encourages documentation and has iterated heavily on its documentation tooling. I love that I can just fire up an iex console and go `h Module.some_command` and I'll get great docs back. And then `@doctests` that both work as inline unit tests as well as low-cost documentation for the library author. I think the incentives to make good documentation are there, and that has inspired the community to document well. And then there's elixirforum.com if I get stuck. In constrast, many times a Django extension has left me wanting in its description about intended behaviours.

>> Phoenix also feels a little bit magical in the way Rails is

>

> I've felt this about every backend web framework I've encountered, Django included. There's a tension between reducing boiler-plate, and not having directory structures/symbol names/etc. have some implicit order to them. If you want explicitness, don't use a framework and maybe use something like Flask/Werkzeug

One of the things I love about phoenix is how little magic there is. Not directed at you, but I agree there is always some amount of "it just works" with a framework but Elixir/Phoenix felt immeasurably more "the code is here" vs "well that particular thing is method_missing'd a few layers down into this which routes into that and then kaboom, here's your entire app."

This is helped by Ecto, which is the perfect mix of helpful and not helpful to me. It gets what I ask for and only what I ask for. It tells me when I've mucked up and generally it feels like a nice API to SQL vs its own thing (and dropping custom SQL is super easy). The data layer is most often the most hidden magic layer in frameworks IMO as routing some HTTP GET to some controller/function/whatever is pretty simple and easy to reckon.

Agreed, Ecto is the perfect balance of helpful and explicit. It allows people to avoid the performance footguns of typical ORMs, while still providing a friendly way to do that relation mapping, pluggable way to do validation, etc. and there are just things you can do with joins + select that an ORM can’t do, but Ecto can.

The magical parts of Elixir/Phoenix, would be the naming conventions of Controller/View/Template (which I think can be overridden), and `use` which brings a lot of useful functions but it isn’t obvious to a new user how to source docs for that.

Oh my god, why didn't I know about "h Module.some_command`. Thanks, that is going to be really helpful!

Will be reading the IEx documentation more closely.

There was a really great talk at ElixirConf 2022 with this tip + loads more. [1] Definitely check it out!

[1] https://www.youtube.com/watch?v=BotVs6TXR-c

> Thanks, that is going to be really helpful!

That makes me really happy :) And if you prefer docs in web-form, just look up any module in hexdocs.pm . Also can't overstate how helpful elixirforums.com is - a lot of smart + helpful people on there.

It is one of my favorite things about the Elixir REPL, and the ease of using them is a great incentive to write docstrings for your own code. The way examples integrate into the docs and test suites is really cool too.

Yeah you got bitten by the 0.15-0.16 transition in live view. My condolences.

Documentation across the elixir ecosystem is pretty good, I find. I am way more comfortable in elixir ecosystem docs over python ecosystem docs.

The transitions from about half of the versions between 0.3 and 0.10 were worse for me. From 0.10 to 0.15 were smooth. 0.16 was tied to phx 1.6, which made it worse again, but I didn’t find it that bad.

0.16 to 0.18 has been mostly okay again, but I’ve seen bugs introduced into an app just by adding IDs to HTML elements with a phx-hook on them. This is a problem since heex templates enforce that each hook does have an ID. It’s also strange that a totally new ID never used elsewhere in the app would break existing JS interop, but it does and it’s what I’ll be working on this week so we can continue upgrading…

Not sure what it’s going to be like upgrading to Phoenix 1.7, but I think it’s going to be a major undertaking and unfortunately most my Phoenix-related screencasts will become obsolete. Elixir itself and Ecto have been really stable, though.

Right, Phoenix LiveView has been pre 1.0. We try to keep things deprecated for a while but we need to balance getting to 1.0 and supporting existing code. Now that it is getting closer, we can make it as a default in new Phoenix apps. :)

phx-hook always required IDs. They would misbehave (and warn) if you forgot the IDs, so could it be that you were relying on broken behavior? In any case the IDs can be enforced now, so it should be consistent, please file bugs if it does not work.

Upgrade to Phoenix v1.7 should be painless, because it only really changed generated code. Screencasts that use generators will be out of date though. In other words, best practices evolved (as they should) but code still works.

I don’t see reliance on broken behavior around the hook, but it’s absolutely possible. It’s a large app with a lot of technical debt and was on Elixir 1.9, OTP 22, LiveView 0.4 and Webpack 4.x when I joined on this summer.

The existing team had encountered a lot of pain dealing with LiveView and made heavy use of jQuery as an escape hatch. They were seriously considering a rewrite in another language not long before I joined.

It’s been a long, painful slog upgrading, but the app is now working with current Elixir and Erlang versions and runs on my M1 Mac now at least. LV 0.16.4 runs on prod and 0.17.5 is working on an upgrade branch (as long certain phx-hooks don’t have an ID).

I’ll get to the bottom of the various issues and get the heex migration finished. Ultimately, I’ll remove the currently hooks and related JS entirely and replace the modals that rely on them with pure LV versions. Just reporting the dev experience.

IMO Phoenix upgrades were pretty trivial since I started around 1.2, until LiveView. Now, due to the increasing LV integration, it feels like Phoenix itself is no longer 1.0.

Great job on the upgrades!

FWIW, if an element does not have an ID, then it is hard for morphdom to track when it moves around on the page. This will lead the hook to consider it is has been destroyed and mounted instead of updated.

About Phoenix, the generated apps definitely evolved a lot, but updating your Phoenix dependency should just work. If it doesn’t, please file a bug report!

Will do and thanks for making such a great language to work with!

One of my first thoughts when I saw the changes to LiveView was "What does this mean for the AlchemistCamp videos"!

Well, I did make a conscious decision to hold off on videos about LiveView (and part of my book) due to the frequent breaking changes in the LiveView series I did back in 2019.

My job has been giving me a lot of ideas for new content, though.

I guess that's heex. I don't like JSX style but the it's not as crazy as javascript. It's okay. With first-class function, passing a thunk that returns template (not in plain string) around is also extensible. But slot is also okay to me. The trade-off of compile time construct is it's harder to do thing in dynamic way.

Elixir docs is top-notch, well-organized. Typescript docs is a mess category-wise. Believe it or not Typescript code is going to be buggy than dynamic typed elixir code because it has better defensive mechanism (pattern match + guard + immutability). The only thing I agree is macro, it's designed for human DX .. good though is hard to do interop (programmable).

What's "magical" about Rails...I really dislike that criticism because it's an inaccurate cliche. Rails has great documentation and common sense (for the most part) conventions. Try doing something in Spring and tell me your experience ... it can easily be described as "magic" unless you read a massive amount of Spring documentation.

I admit it's a long time since I used Rails and Ruby, and it was around the same time I was learning Python and Django back when Rails was the hot thing - but Django seemed to be more straight forward and less of "So why is this working". If you read the PEP20 Zen of Python that resonates much more soundly with me particularly "Explicit is better than implicit."

This drives me nuts for example: https://guides.rubyonrails.org/layouts_and_rendering.html#re... - ok it's automatically parsing and rendering that template, based on that route and controller and it's less code but less explicit. And it assumes that we have written all the filenames correctly.

Which it's a pretty fair assumption: you would create all of those files through generators, eliminating the need for writing boilerplate. And make the name explicit if, for any reason, your template is located somewhere else.

I am not a huge Rails fan, but in this particular case I see zero issues with how Rails does things.

Your assessment is similar to mine, set aside any cool features of the language, maintaining an Elixir app is the problem. The constant API shift with each LiveView release, not enough people maintaining hex packages, not a large amount of hex packages available forcing some things to be built, etc. Adoption in our organization was halted because of the messiness of upgrade path in Elixir as a whole. Projects that were built on earlier versions suffer the most pain where developers will spend like a week sorting through code changes needed to update. There are some neat aspects of Elixir but the maintenance trade-offs aren't worth it in management's eyes.

LiveView's growing pains were definitely pretty bad (the early days of it had some pretty obnoxious breaking changes), and I can see while still disagreeing about the magic comment, but what's wrong with Elixir's docs? They are, hands-down, the best language docs I've ever interacted with, and that very much includes C#, so I'm a little baffled as to where that complaint comes from.

I agree with your assessment. You have to know what you’re signing up for. Remaining in the JavaScript ecosystem still maintains many tangible benefits.

I don't think you should be downvoted, you gave it a fair shot and concluded it was not for you.

Well I am on the fence at the moment. Perhaps I should be downvoted for being indecisive!