fireproofsocks

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

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

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

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

Where Next?

Popular in Questions Top

Darmani72
If I have a post route which an argument: post /my_post_route/:my_param1, MyController.my_post_handler How would get the post params ...
New
gshaw
What is the idiomatic way of matching for not nil in Elixir? E.g., First way: defp halt_if_not_signed_in(conn, signed_in_account) when...
New
fireproofsocks
I’m working on defining a simple Ecto schema for a table (in PostGres), but I don’t see where I can define a column as NOT NULL. Conside...
New
tduccuong
Hi, is there any work on GUI with Elixir, that is similar to Electron/Javascript? My idea is to bundle Phoenix and BEAM into a single se...
New
Lily
In templates/appointment/index.html.eex: &lt;%= for appointment &lt;- @appointments do %&gt; &lt;tr&gt; &lt;td&gt;&lt;%= appoi...
New
joeerl
Hello again - after a longish gap I’ve decided I really must dig into Elixir and see what’s been happening here - so I have a few questio...
New
RisingFromAshes
I’ve read in another post that it may be possible with a router helper - but I couldn’t find an appropriate one, and tbh, I’m still just ...
New
JDanielMartinez
Hi! May someone helps me, please! I have two apps into an umbrella project: the first one is Database, which manages queries, and the se...
New
hariharasudhan94
I would like to know what is the best IDE for elixir development?
New
PeterCarter
There are pre-rolled solutions for other frameworks that do work. However, Phoenix does not seem to have these. Have people had good expe...
New

Other popular topics Top

sorentwo
Hello! tl;dr Announcing Oban, an Ecto based job processing library with a focus on reliability and historical observability. After spen...
985 42920 311
New
AstonJ
Posting this to see if we can make things easier for people to get into Neovim. If you use Neovim and have a favourite distro please let ...
New
greenz1
I have a phoenix application from which a user can download multiple(5-6) files of size 1MB. I couldn’t find anything related to sending ...
New
Patoshizzle
After calling mix ecto.create I get this error: 17:00:32.162 [error] GenServer #PID&lt;0.412.0&gt; terminating ** (Postgrex.Error) FATAL...
New
JeremM34
Hello, how can I check the Phoenix version ? Thanks !
New
chrismccord
Phoenix 1.4.0 released Phoenix 1.4 is out! This release ships with exciting new features, most notably with HTTP2 support, improved deve...
688 30877 112
New
msaraiva
Surface is an experimental library built on top of Phoenix LiveView and its new LiveComponent API that aims to provide a more declarative...
564 43622 214
New
vonH
When I run the Plug and I recompile I wind up having to use Ctrl C to quit iex and start again. Witht the help of rlwrap I can use the cu...
New
fayddelight
I tried installing elixir 1.11.2 erlang 23.3.4 via asdf in my zsh shell. Enabled the versions locally and globally. When I list them ...
New
klo
Got a question about when to concat vs. prepending items to list then reversing to achieve appending. So i know lists boil down to [1 | ...
New

We're in Beta

About us Mission Statement