I could post several specific questions about problems with several specific queries, but I think it’s fair to ask a more general question: what is up with the Ecto Query documentation? The examples seem to have gone out of their way to strip away any context and avoid providing a full working example at all costs. It’s madness.
When I was working through some of these problems during the last project I made a pull request that simply added some examples and clarifications so others wouldn’t have to suffer through the same confusion that I had: https://github.com/elixir-ecto/ecto/pull/2399/files That hasn’t been built and deployed to Hexdocs yet – why does it take so long? Such a slow release pipeline does not incentivize developers to contribute to the projects, and it probably explains why so many “satellite” articles are orbiting the official docs, desperately trying to fill in the holes that the official docs have left open.
I think something happened with the release because that commit is not present in v2.2.10. It is, however, in master.
I felt like there was something missing with the association docs, but have been pretty happy with the documentation so far. I’ve experienced worse with proprietary products. That said, documentation that helps clarify is always welcomed and I think it was sincerely a mistake and not intentional that your changes aren’t present in the hexdocs.
Those articles always struck me as just rehashing the ecto docs ¯\_(ツ)_/¯
2 Likes
Exactly… they have in almost every case omitted the same critical pieces that would make them useful references.
That’s one of the backdraws of keeping documentation with code. Code is released in version and if there are no new versions or a new major version is being worked on and docs updates are not manually backported into the old version’s branch it can easily take a while until changes are actually on hexdocs. This is especially noticable on libraries with long running release cycles like e.g. ecto or phoenix.
1 Like
