How to suggest revisions to the documentation?

Questions / Help
1

Hello,

Does anyone know how to suggest revisions to the people who maintain the documentation, please? In particular, I think there are a couple of typos in

https://www.erlang.org/doc/design_principles/statem.html

Thanks.

3 Likes
2

Edit this file otp/statem.xml at 51f2165d19fe90ebd34c7bd16ad5c78c3dbdfad3 · erlang/otp · GitHub and make a PR.

3 Likes
3

Alternatively, if you hover your mouse over a section heading, two icons will appear next to it on the right. The pencil icon lets you edit the text and turn it into a PR.

Btw, @starbelly is currently working on that chapter, for other reasons. See Adjust language around the usage of receive in a gen_statem. by starbelly · Pull Request #6294 · erlang/otp · GitHub.

3 Likes
4

Another option is to open an issue on the Erlang/OTP GitHub repo., discuss the changes, then apply them. Even though a PR is often faster, a prior discussion can give you hints on why the doc. is the way it is, and maybe lead potential changes in the right path. Typos only, though, I’d go with @Maria-12648430’s suggestion.

4 Likes
5

Yeah, if there’s some typos you see in this area @Cozza, let me know, we can probably just fix them up while I’m in this area :slight_smile:

3 Likes
6

The rule of thumb I go by in documentation issues is like this:

  • If it is only typos, or a few words to change, I use the pencil thingie I mentioned.
  • Otherwise, when I’m sure that what is written is wrong or positively misleading and that my rewording will improve things, or if it involves any messing with the XML or larger changes, I will branch, do the edits offline, then make a PR and discuss everything there. While this is not as convenient as the pencil thingie, I can run make xmllint and make docs on it to see if everything is at least structurally correct before pushing; the pipelines will do that too eventually, but as they run all checks on everything, it takes a long time only to see that you have made just a tiny mistake and then do it all over again
  • If, contary to the former rule, I’m not sure if I would be improving things or not, or if I’m at a loss what a better wording would be, I open an issue.
3 Likes
7

Thanks for all of your replies, I’ll do as you suggest.

2 Likes