Hello, is there any chance that a user contributed notes section, like the one in the PHP documentation, can be added to Hex docs? It would be nice to have something similar to the new anti pattern docs on every relevant module page, but more in depth. The forum is nice but it would be nice to have a quick summary of all the gotchas in one place.
While I did really enjoy those comment sections back in my PHP days with Elixir, just make PRs. José and co. are amazing about doc contributions. PRs are usually reviewed within a day. I’ve once had one accepted in under 20 mins from opening it! The big benefit here is that it gets vetted by the team and doesn’t have to rely on an upvoting system. José has even added to and reworded a PR I made to improve it. That particular contribution was largely centred around a gotcha much in the spirit of those PHP comments 
So even if you are unsure about what you’re contributing, it will get the ball rolling and others can help to fix it (or you can post it here first, of course).
Otherwise, hexdocs are static HTML so I think implementing a dynamic section that would require an upvote system would very likely be a non-starter.
4 Likes
Yeah, hexdocs hosted docs are heavily cached on a CDN. People are using external tools like e.g. Dash to browse docs. And most importantly docs are not just exported as HTML, but at least also in epub format, but generally any format someone builds a formatter for.
A dynamic comment system would at best cover only a small subset of usecases around elixir documentation - unless comments would also somehow feed back into where documentation is built.
Additionally one may not forget that once you allow people to post anyting to a public place you need people to moderate that – which in the age of AI only becomes an increasingly more complex task.
All that said I want to mirror @sodapopcan post that improving the docs themselves is the more scalable approach, even if it requires maintainers of libraries to collaborate to get those changes in.
1 Like
