Hologram Documentation Updates/Feedback

I’m excited to announce that a new Actions documentation page is now live! This page provides comprehensive information on how to use actions within the Hologram framework.

You can check it out here: Actions Documentation

Feel free to explore and let me know if you have any feedback or suggestions!

I would say that highlighting for code blocks goes a long way here, especially since you decided to go with a custom platform, personally I would just used hexdocs.

I do agree that syntax highlighting is probably table stakes.

I’ve been pretty impressed personally with how far I can customize ex_doc into some extreme stylistic changes; and the cross-linking between other docs in the ecosystem is luxuriant. The auto-genned TOC and deep linking, including back to source, is hard to recreate on my own (I’ve tried, though I’m not a wizard at this stuff).

OTOH I do understand the desire for a web framework to boostrap its own docs, to which I can say that prism.js works pretty well in my experience.

Very excited to see more docs, everything I see about hologram suggests a functional API exactly how I would want it to work. The unveiling of topics incrementally has me on the edge of my seat.

I notice upfront the signature of a def action is clarified, and then a lot of useful demonstrative snippets are under the heading “Action Results”. These snippets are individually illustrative but I think the section could use a “bring it all together” example.

Notably, as documented today it’s not clear if the calls under Action Results cause side effects, are chainable, or part of some undocumented expected contract between Hologram and what the end user is supposed to do. My experience with Phoenix tells me they are probably meant to be composed via pipes and that the return value must be some Conn-like object, but that should be made explicit when you get the chance!

See:

Actions must return a %Component{} struct. This struct not only reflects changes to the component’s state but also includes instructions for what happens next. These instructions can be in the form of a chained action, an enqueued command, a next page to navigate to, or an emitted context.

For more it’s clear enough …The only confusing thing is that’s part of Update Emitted Context section. I would move it right below Action Results header.

Ah I did indeed miss that in its entirety, I suppose I was scanning the code snippets more throughout that section. I’d still say a more demonstrative complete example would help, but… so would me reading closer

I like the idea of having a dedicated site for docs besides mixdocs. The default docs are usually good, but sometimes I found some undocumented parts because people generate documentation from modules and probably forgot some parts. This happened to me recently in Phoenix where I need to go into the module to see what a function returns, to find out which parameter to pass. I think this type of “approach” is good for developers outside the ecosystem, it’s like the the beginning of microsoft or apple (I don’t remember correctly the history), elixir developers will say that you only need mixdocs (the baremetal hardware) but why not have more carefully designed and created documentation in the standards that other languages and users are used to know? ​​

to add more 2 cents bcs i’m having this experience of being new to elixir eco: I feel like more high levels languages as python has more “newbie” friendly docs (probably bacause the language is more abstracted) and elixir/erlang ecossystem packages forces me to have more knowledge over the language and the domain to follow and understand corretly the docs (and I think this is good).
To make me clear, when I use a python os js library is rare that I dont see something documented (even if its something silly)
in elixir the majority of time that little thing isnt documented and I have to seach throught internet, this forum that I very much like, or throgh annotations; what again, it’s good because makes me a better devloper, but you know would be good to not have to

This is why you can always generate separate markdown files to cover something that is outside a single module. For example, here is the phoenix installation page that is simply a .md file.

I don’t think anyone claimed that going with a custom solution is a bad thing, however ex_doc has already implemented a huge amount of great features that you will have to implement from scratch.

In this regard I agree, had this situation too, for example OTP has much better structured documentation, where every parameter and it’s possible values are documented entirely.

It does seem that the last years elixir is moving in that direction too and the fact that erlang switched to ex_docs seems like all required features are in place, it’s up to library creators to document properly.

Care to show examples of those standards? All the ecosystems I’ve worked professionally with had some of the most horrible documentation, I had always to resort to reading blogposts and tutorials of dubious quality.

“Care to show examples of those standards? All the ecosystems I’ve worked professionally with had some of the most horrible documentation, I had always to resort to reading blogposts and tutorials of dubious quality.”

I was talking about documentation sometimes requiring a lot of technical input from the user with a “single code sytax” or “single code” instead of putting more declarative english documentation (besides annotations), coving more than one case and edge cases , etc
in resume I think elixir documentations are better takinginspiration from other languages ​​and libs to improve its own documentarion style or pattern (not becoming them) making it more “easier” and with higher coverage (dooh this is good for every documentation) than locking yourself in your own style

“It does seem that the last years elixir is moving in that direction too and the fact that erlang switched to ex _docs seems like all required features are in place, it’s up to library creators to document properly”

the perfect approach would be build the base layer on exdocs and kind of transpile it to the doc third repository? can this be done seamlessly?