I would define things a bit differently:
- you have users, but they are also fitting into different categories: are they long timers in the community? New joiners? junior engineers or experienced ones? Are they people with or without experience in functional languages? Documentation written for experts (often reference content) tends to have a different shape from documentation written for people who have limited functional programming experience or none at all (often more tutorials)
- you have developers who wrote the code the documentation is about. Here again there are differences depending on where you are: is documentation an afterthought? Something added after writing code? Something done as part of writing code? Are the developers receiving any training in technical writing or is any toolchain provided to them?
- you have technical writers, maybe. Most places don’t. Some places have them, but you might have one or two per department or company, and they also write public copy for marketing material or end-user documentation not intended for engineers building with what is there. Some places give you one technical writer per team. The lack of actual formally trained technical writers is why we see a term like documentation guy, the same way we tend to have engineers write their own tests and we see fewer and fewer tester roles out there, even if they still exist.
The thing that’s missing in your overview is that very often, these 3 roles are done by the same person: the engineer writing the code has to write the docs for themselves and the rest of their teams, and the same documentation is made available to external users.
If your documentation tool is less pleasant for more perfect results, you’re trading that off on your engineering time for other issues.
This has knock-on effects: if you find yourself receiving contributions from the public, who may already be familiar with other tools but not yours, your maintainership turns into a job of validating commits and writing docs (which the original contributor now has to validate, rather than writing it themselves), for example.
And so while I can understand the arguments going in favor of what is the theoretical ideal for producing the best documentation around, my experience with the Erlang community is that the thing it has the most glaring lack of is people with time and desire to contribute. There’s more work to do than people available to do it. This is true of the core language, of the toolchain, and of the foundation. This doesn’t mean there are no contributors or that the existing ones aren’t appreciated, but that the roadmap maintainers would wish to hit isn’t realistic under their current workforce and contributors.
I’ve not been directly involved in this change but I’ve seen ongoing discussion about it over the course of the last year or so, where most of the contributors aligned on the need for a change in the implementation format but most of the issue was on the redaction format. You can see this more closely in the list of EEPs that were required for that change as well:
- EEP 48: Documentation storage and format (~Jan 2018)
- EEP 59: Module attributes for documentation (~Feb 2022)
Ignoring the advantages coming with these changes (aligning toolchains across parts of the community, integrating with other testing or publishing tools), this appears to partly be the very frequently seen outcome of decision-making as done per communities of volunteers: The people doing the maintaining and the volunteers involved in the decision-making aren’t the same people as the critics, and the critics present in the room at publication time aren’t the total set of end-users either.
My intent here is not to say “if you don’t want surprises, get involved” because it’s frankly unrealistic to expect everyone to be involved in everything all the time, and I hate the “you had to be there if you want to say anything” line. Some of these changes are seemingly years in the making, and the current Erlang documentation format has been pointed out as a blocker often, albeit by other people than those here, including people submitting changes to Erlang/OTP itself.
Anyway I wanted to point out that the distinct user sets are possibly true in some work environments, but the user/developer/writer distinction does not really exist in this specific case.
If the criticism of the changeset does not recognize this reality, it is criticizing a change without a proper understanding of the workflows it aims to change and correct and instead works on a mistaken ideal that doesn’t exist.