Hey Bart and all,
I’m not sure if this has been talked about before (I’ve looked but of course I could have missed it) but one of my biggest pain points with working with Hologram is that the full documentation doesn’t live in hexdocs. This is not a dig at the website, it’s fine and works and I can find what I need, but it would be so much more convenient if it lived in hexdocs. It’s familiar, I can search it, I can use h in IEx, and it can be used with tools like Dash. The other big thing is that the Hologram website is in a private repo making contributing to documentation quite hard. It has occurred to me that perhaps this is by design for the moment so you don’t get flooded with PRs?
In any event, how do you all feel? Also, @bartblast, is Elixir Forum the right place for this kind of feedback? Wasn’t sure if I should have opened and issue first.
2 Likes
Hey Andrew, totally fair feedback!
I actually addressed this in detail some time ago - check out this post: Hologram Documentation Updates/Feedback - #21 by bartblast
TLDR: The Hologram website is meant to evolve into an interactive educational platform - think component playgrounds (like Storybook), real-time demos, community showcases, AI-powered assistance deeply integrated with framework internals, and more. HexDocs would either make some of these impossible or constantly get in the way. The site is also built with Hologram itself, which is valuable for dogfooding and as a real-world showcase of the framework.
That said, nothing prevents us from adding the features you like about HexDocs - search, Dash compatibility - to our own docs. Those are on the radar. Dash support is definitely doable with a custom site, and this kind of thing would be a great area for community contributions eventually. As for h in IEx - that actually already works for Hologram since every public function is documented with @doc. There’s also an API reference on HexDocs: https://hexdocs.pm/hologram
As for contributing to docs - I do plan to make it possible to suggest edits directly from the website. There are a few things I need to build first though, like a macro component feature, before that can happen.
And yes, Elixir Forum is a perfectly fine place for this kind of feedback!
Ugh, I don’t know how I didn’t find that. It was oddly not suggested to me when writing this up and the one I found (that I remember when it was posted) was this.
So that all sounds good to me! My only issue would still be with h in IEx, which I know works but they are shortdocs. It’s really more that I like to jump to def in libraries and read the docs there at times, but it’s not a huge deal. Otherwise I just really like hexdoc, but the advantages you listed all make sense to me (and are exciting!) so ya, I’m all good now, lol.
Thanks!
I think having all documentation for all packages is a huge, immeasurable benefit for the elixir ecosystem. It’s one of the selling points of elixir for my team.
It would be a huge shame if hologram is an exception.
All right, if I’m being fully honest I do agree with the noodle, but I do understand the trade off if it’s not possible. Unless something was built that could grab docs from source and convert to Hologram pages, which I’m not expecting anyone to do any time soon (or ever) lol.
