fireproofsocks
Where can we submit documentation updates to Hex packages?
I know I asked this before (I even submitted a PR somewhere), but now I’ve forgotten the steps because the flow is so obfuscated. Where do interested developers submit changes to the documentation of Hex packages? I may be missing something obvious here, but where are the docs stored? I’m expecting a link to the source code repository that controls the documentation. Instead, the only links I see are irrelevant ones (e.g. ExDoc is generic, not a link to the specific documentation/package that I’m looking at). As someone who is driven to a soapbox when it comes to the importance of writing good documentation (https://medium.com/@craftsmancoding/wtfm-dbbec02eb172), I’m wanting to see a few critical things that appear to be missing in the Hex packages.
1. Where is each packages code’s repo located? If I want to view the source code or fork it, where is the link? Am I to assume the code is always in Github? Bad assumption methinks. Make it clear and put up a link as flagrantly in our faces as possible: This code in this package is stored in this repo: _____
2. Where is the link to the documentation’s repo? Every bit of documentation REQUIRES a feedback loop, no matter if it is an open source package or proprietary code. Every Hex package MUST have a link to where a developer/user can suggest changes to the documentation. Although I’m new to Elixir, I have already seen lots of well-constructed code… but I’ve been forced to slog to some pretty rough-shod docs to get to it. There’s really no excuse for that, and I know I’m not alone in that struggle. Unless there is a clear link for users to submit suggestions to documentation improvements, the adoption of any package or system will suffer because the documentation is static and it stagnates. It’s as dire of a prognosis for a package as having your mouth sewn shut. I think we can do better by implementing a few minor changes.
Thanks!
Most Liked
OvermindDL1
I also vote that there should be a link to the hex.pm package page for a given package in the menu for the docs of a project on hexdocs. There have been a number of times where I want to jump back and typing it out manually is long and error prone.
fireproofsocks
Thank you for the response!
Ommissions/unclarities or changes to the documentation are considered as implementation bugs by most Elixir developers, so they can be requested in the main project’s issue tracker.
You can see how maddening it is to NOT have the link for that up-front and center. How hard would it modify ExDoc to read the links specified in the mix file and print that up in the top left-hand corner of each page?
joaquinalcerro
I recently contributed to ecto documentation and at first I was confused on how to contribute. This was my first time contributing.
When you go to the “Online Documentation” link, you are presented with a Web Site you assume you can modify or contribute to. Well, at least I did. I even ask someone in the ecto team how can i contribute but never got a response back.
So I wasn’t going to stop investigating how to do it and I found the “</>” button that took me to the Github source code of ecto. Even though I knew about ExDoc and how to document a module inside the same code file, I wasn’t aware that the hex.pm site was built with it.
I finally realized that I had to go the github PR way to contribute and did it.
So based on my experience I recommend you to add a simple “How to contribute to packages/documentation” section in the hex.pm site that will help new contributors. Maybe not experts. This simple section should explain how ExDocs works, what is the “</>” button for and the steps to follow to contribute to any package.
I understand that hex.pm is the package manager for Erlang ecosystem but seems so natural to be guided here on how to contribute to a open source project.
Sorry for the long story… Best regards
ericmj
I have opened an issue for this on ex_doc [1]. We also want to add a version selector directly on the hexdocs page so you can jump between versions directly on hexdocs. These features are tricky to implement because hexdocs does not control the content it hosts, documentation is statically generated by ex_doc when the package is published and uploaded to hexdocs which only serves statically generated .html files via AWS S3. So we need to figure out a way to add dynamic content to ex_doc/hexdocs or fundamentally change how they work.
michalmuskala
What if ex_doc standardised on having a versions.json part inside of the package and hexdocs would update this file for all released versions when a new version is pushed?
Popular in Questions
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Supporting innovation across the BEAM ecosystem.
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Develop your skills with books, videos, and courses.
Enabling companies to succeed by building software people love.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"