ux feedback thread

[haxscramper]

Continuation of the #108 (I didn't have permissions to move this issue, so I copied it directly to discussions)

It might be a good idea to think about people contributing suggestions to the documentation and user experience. At the very least, we can have a GitHub discussion thread for discussion about nuances of the documentation (manual, spec, or stdlib parts) and suggestions about improving error messages.

Most likely people won't open issues about ambiguous phrasing in documentation, and "edit" button is almost useless, but if we make it easier for a beginner to contribute their view on the matter it could make a difference in the long run (it is beneficial for us to know about bad documentation as soon as possible).

Alternatively, it can be a #docs/ux-team channel on matrix, or any place where we can get to details about missing explanations.

Bad documentation has been repeatedly brought up as an important issue, but when asked about specifics, people usually can't recall which part exactly it was. We need to make it easier for people to tell us something is missing when they realize it is missing.

I think I repeated the same idea at least twice, but tldr version is - we need to make sure people without the curse of knowledge are given the easiest way possible to contribute to documentation.

[haxscramper]

by @saem

I'm definitely supportive of the concrete suggestion that I'm gleaming from this issue.

Only thing I ask is to add these hard requirement to the concrete solution(s):

1. it must be easy to trace from documentation to relevant code sites programmatically
2. It must be easy to trace from code site to documentation programmatically

---

Intended use of the about requirements

By way of the requirements above, the following class of scenarios just be easy to do as programmatically as possible:

1. If a feature is being changed it's possible to see what needs to be updated, code and docs
2. If a feature is being retired it's possible to see what the code and docs graph is
3. If some code i needs to be understood, it's possible to learn what features it's a part of, how it interacts with other things etc

Why the requirements are worth it

One way to look at it is that our documentation based workload shouldn't ossify or lock into place bad design. If we can't improve the language because changed to docs are hard to track down then the documentation system is completely broken. I don't want to document bad design and make bad design hard to fix. I also don't want to overburden contributors with massive documentation upkeep expectations.

Clarifications

I'm not assuming all documentation is code comments here. For example of we had cookbook/recipe for nimskull, like "how to write small switch based interpreters for a macro based DSL". We need a way to see the dependencies out from it and form elsewhere back to it.

In the above, mechanisms like runnable examples, metadata, reusable by reference excerpts for errata/known issues, etc are key enablers. To make sure the army of knowledgeable fresh minds who see clearly the documentation gaps don't overwhelm the wizened minds that can simplify and scale the language.

[haxscramper]

The basic idea is to create and maintain a proper feedback cycle from new users/maintainers. They walk through the sequence of choice points, like [want to contribute] -(next?)-> [reading awailable projects] -(next?)-> [reading issue] -(next?)-> [writing code to solve issue] -(next?)-> [making a PR]. Each (next?) is our responsibility - we need to make sure user can transition from state 1 to state 2 etc.

If they are stuck at some point, we basically ask them to tell us that "(next?) between stage 3 and 4 is bugged" so we can fix it.

Of course, it is a lot more complicated in terms of choices that the user has to make, but the general idea stays the same.

Until we are sure the onboarding pipeline is working correctly (which is not possible to fully ensure), we have to know on which intersections users are having troubles.