This thread is dedicated to announcing updates to the Hologram documentation, as well as discussing any ideas for improvements and suggestions for new sections. Your input is invaluable in ensuring that the docs meet the needs of both new and experienced users.
Feel free to share your thoughts and ideas here to help enhance the documentation and make it more useful for everyone in the Hologram community. Let’s work together to make Hologram’s documentation the best it can be!
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 _docsseems 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?
now I understood what you was saying, totally agree!
Care to show examples of the said documentation from other languages that in your opinion is better than elixir? Just claiming that other languages have better documentation without arguments is not very constructive.
For example rust is a great example, for example tokio library. Great documentation and examples, even though I would say this doesn’t differ much from the documentation style of elixir libraries.
Thanks guys @christhekeele, @Eiji excellent feedback!
I added “Putting It All Together” section at the end of the page.
I also moved the section about chaining another actions to the bottom, because this is going to be a rare case.
I moved the section mentioned by @Eiji to the top of the “Actions Results” section and redacted it a little bit to explain that the functions called are pure and the whole process is composable.
The changes are live: https://hologram.page/docs/actions
Lovely, I think that works great as a capstone to the learning presented in the rest of the guide!
3 posts were split to a new topic: Hologram website navigation problems on mobile
not muich singular cases, i’m refering about day to day use, I feel like more high level languages has a more noob friendly documentation, while elixir requests more from the user, try to check the most initial guide from libs like Numpy and compare to what you usually see in elixir
While building a custom website is significantly more time-consuming than using HexDocs, I believe it offers several key benefits:
.holo template syntax, which needs special treatmentYou can do that! Simply create a package named like makeup_holo and use makeup API to register your lexel, see application.ex | MakeupEEx 1.0.0 @ GitHub.
Fine, but you can use hex to store documentation and create a standalone AI chat bot for it, right?
Ok, the sidebar is always on left, but there is no problem with navigation at all. Simply use heading tags in markdown like ## Examples. If you have some ideas to enhance navigation then you can propose changes to ex_doc.
Since across many versions there are different assets and they do not change (in specific old version) when hex is updated you should be able to override the assets. In doc/dist you can find CSS, JavaScript and even fonts, so it should be not a problem as long as you don’t want to change DOM and I guess that you could also change JavaScript to support your AI as well.
You can open documentation in LiveBook. If remember correctly you can even create custom cells. As far as I know it’s even possible to start Phoenix server from LiveBook, so if that’s not enough for you then I have no idea what you need.
Oh, I forgot to mention that there are some options that you may find interesting … Please take a look at Extensions @ ex_doc documentation section to see how you can inject custom CSS and JavaScript, so you don’t even have to touch generated doc directory.
© Copyright Elixir Forum | Terms | Privacy & Cookies
