Hacker News new | ask | show | jobs
by LeonenTheDK 2053 days ago
You might be surprised to see the quality of the docs in the Elixir world: https://hexdocs.pm/phoenix/Phoenix.html
1 comments

That looks … like many Python projects? It's slightly prettier than the default Sphinx theme but I'm not seeing anything which wasn't common a decade or two back.
IMO part of the quality here is these docs are generated from comments in the code. All you have to do is document your functions and modules properly, run a command, and you have an entire set of docs.

It reminds me a lot of JavaDocs, although I never used them extensively. I'm also not very aware of how documentation looks in the Python world.

Another interesting thing is the code examples. You write them in the comments as "Doc tests", and they are run and tested like normal tests. This means that all the code snippets are up to date with the latest version of the project (as long as you do test!).

The best part, also imo of course, is that it all works out of the box.

That’s how it works in Python, too. You add text descriptions (docstrings), automatic documentation generated from function/class definitions (comments can add prose), and you can run doctests to test things like examples.

See e.g. https://www.sphinx-doc.org/en/master/index.html and https://docs.python.org/3/library/doctest.html

Very nice, I'm glad to see it elsewhere. Maybe Elixir even took inspiration (or it's just a plain good idea). I'm really surprised that I had never heard of or encountered it, maybe it's just an accepted part of the ecosystem so no one talks about it and/or I assumed everything was written manually. Also haven't used Python professionally which doesn't help.
Yeah, I don't care who came up with it first as much as it spreading widely. We waste far too much time on bad documentation as a field.