Advertise documentation generation better

[Lilja]

I'm very new to BEAM/Gleam. I checked it out and tried to read the gleam_erlang-docs, where I found a documentation typo that has since been fixed.

Since I'm not familiar with the ecosystem around erlang and its syntax of writing documentation or building it. I ended up blindly doing the change in the pull request above in the github GUI, if it weren't for the similar setup of one of the other functions that were correctly formatted I wouldn't be able to do the change properly.

Initially, I tried to look into the Gleam language tour page for how to understand how to write and develop the documentation pieces.

Some questions/reflections that I made when trying to correct the typos:

• Is the documentation generation some sort of home brewed system? Or is it shared with other programming languages in the erlang ecosystem?
• What is the relationship between gleam and hexdocs?
• This page mentions a way to write documentation comments, but there is no reference to how to do more advanced things. I was looking for how to write hyperlinks.
• Can I git clone that package and get my own local documentation page so I know my change was correctly formatted? (It wasn't until just now that I understood gleam docs was a subcommand)

Maybe some of these questions can be incorperated/expanded into the language tour?

[lpil]

Hello! Yes, we need better documentation here. I'm not sure exactly where all this information should go, but it is needed. The language tour is only about the language, not the tooling, ecosystem, etc, so that cannot be the home of most of it.

Here's the answers to your questions there:

Is the documentation generation some sort of home brewed system? Or is it shared with other programming languages in the erlang ecosystem?

We have our own documentation generation in the build tool.

What is the relationship between gleam and hexdocs?

Hexdoc is a website that hosts documentation. It has no opinions about how you make your documentation.

This page mentions a way to write documentation comments, but there is no reference to how to do more advanced things. I was looking for how to write hyperlinks.

The format is markdown! I'll update the tour to make sure it includes that.

Can I git clone that package and get my own local documentation page so I know my change was correctly formatted? (It wasn't until just now that I understood gleam docs was a subcommand)

gleam docs build --open will do the trick, but it only builds the top level package.