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!

You can look that up on the packages infopage on hex.pm. If the author has put that piece of information into the mix file…

If its not there, you need to google.

Documentation for elixir applications is usually side by side with the sources. So you can find it the same way as you can find the answer to your first question.

There may be other kinds of documentation than only the generated API documentation, but that is specific to the package you use. And since it is non standard documentation, it may be otherwise sourcecontrolled or not at all.

@NobbZ already answered your second question in a lot of detail, but let me answer your first question in a little more detail:

There are two places where a package’s code repository can be specified in the mix.exs-file:

  1. In the source_url key that project returns. This is actually read by ExDoc to automatically link to source files from within documentation files as well.
  2. Inside the package.links key that project returns. Of course, any other project-related links can be put here too.

There is no hard dependency on GitHub at all; any repository location can be used.

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.

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?

3 Likes

Hex docs do already use the repo / website links if they are supplied. Try clicking on the package name in the sidebar or if a repo is supplied the “</>” links in each page (e.g. here). But they’re not required. People can even publish nothing online beside the package on hex. There’s no dependence on git / github or any form of online presence. You just need a local mix project and you can publish it to hex.

Ooof… I did not see that. the little “</>” icon is not doing it for me.

1 Like

Of each page of where? Can you expand on where you expect these links to be and how we can improve the visibility of Elixir library documentation. I believed this was already fairly visible through links on hex.pm and github.com, so any guidance on improvements would be appreciated.

1 Like

I would recommend using a word as the label. Symbols like “</>” are a nice bonus, but they aren’t always clear. I would recommend labeling that with a word. Like “Source” or “Issues”. Look at PHP’s packagist for comparison: https://packagist.org/packages/guzzlehttp/guzzle
It clearly has a searchable label for the git repo, one for source, one for issues etc. It’s much easier to read.

The corresponding page for your packagist link would be something like https://hex.pm/packages/phoenix though. And the “Links” shown there are again based on what authors supply in their mix.exs.

Sorry, I need to ask you again to elaborate on what you expect for links, we use words such as “GitHub” and “Online Documentation” to direct people. The word choice is partly up to the maintainers of the packages and out of our control, but any guidance on improvement would be appreciated and hopefully we can improve the website and guide maintainers in the right direction for their link names.

When I go to https://hex.pm/packages/ecto I find it easier to discover links to the repository and docs than I do on https://packagist.org/packages/guzzlehttp/guzzle. I am not a good judge though since I am used to the design and layout of hex.pm, so any suggestions for improvement would be greatly appreciated.

1 Like

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

3 Likes

I think the disconnect is this: there’s the https://hex.pm/ site (which has nicely labeled links) and the https://hexdocs.pm/ site (which takes some time to navigate). Most of the time when I am searching for Elixir packages, Google takes me to the hexdocs page. I may have bumbled into a hex.pm page now and then, but basically it was on another planet. YES, the pages on hex.pm look very like the pages on packagist.org… but the hexdocs.pm pages do not link to their corresponding hex.pm page.

For example, nowhere on the Ecto — Ecto v3.11.1 page do I see a link to the ecto | Hex page. They are related, no? Why not include links from hexdocs.pm to hex.pm?

1 Like

Thanks – that was totally my story too. And I didn’t realize that hex.pm was really where the packages are registered and links to repos etc. are listed.

The process of contribution is different for about every other package, so I do not think this would help.

Also as a rule of thumb, when I want to contribute to project P, I search for Ps homepage, repository, hosting service, chat, whatever, but I won’t look at a third party package repository, at least its not the first thing I’d look for a guide for contribution (I’d probably use it to discover a homepage or repository).

1 Like

As I said this was the first time. Thanks.

1 Like

Even for a first time, I had not considered to look at third party package repositories, but the actual source code hosting or first party sites.

1 Like

In most open source projects/libraries/etc. I look for a CONTRIBUTING.md file for the exact instructions/preferences to cover things like branching strategy, tests, or coding style requirements… I think that file is what Github recommends for the purpose, and if it is indeed more or less a standard, it wouldn’t hurt to include a link in the hex.pm overview page, but I would be happy if it were easier to find the source repo…

1 Like

Its as easy to find, as the package author makes it to find, but thats not a problem of hex.pm.

As I mentioned in another reply, the biggest disconnect here was I was only looking at hexdocs.pm (as it is often the only domain that appears in search results). I had literally forgotten hex.pm even existed. I don’t think there is a link to the corresponding page on hex.pm for any of the generated docs on hexdocs.pm (!). Given the critical importance of the information contained on the hex.pm pages, omitting that link is problematic.

Yes, truly, there is a missing link, I often miss that myself, as well as I miss an easy possibility to change the version. A way that does not rely on knowledge about the hexdocs.pm URL-structure…

But those features of hex.pm or hexdocs.pm are unrelated to the way how and if at all package maintainers make the repositories or documentation discoverable through hex.pm or even want contributions.