Make it easy to contribute docs/ux suggestions

[haxscramper]

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.

[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.

[disruptek]

Can we support comment threads on the docs? They don't have to be permanent.

[saem]

Can we support comment threads on the docs? They don't have to be permanent.

Yeah, we discussed that before and it's still a good idea.

[haxscramper]

Haxe doc has separate pages for meaningfully large chunks of documentation https://haxe.org/manual/class-field-variable.html each page corresponds to the GitHub issue HaxeFoundation/haxe.org-comments#83 that people can comment on, and this is linked back to the documentation pages via utteranc.es service

[haxscramper]

Documentation and code traceability, explicit documentation graph construction are todos for haxdoc, we could copy good design to nimskull once I figure out how exactly it would look.

[haxscramper]

Documentation is a bit sketchy I must say. There is a large assumed knowledge base too. When I first started out using the mysql module and deployed something. I spent a day trying to figure out why it wouldn’t work, not realising that my main machine had the mysql dll which I needed to include. Nothing about this in the docs and when I did a pull for it with documentation to notify users of this they said it should be obvious 🤨

While searching for the haxe comment in matrix chat I found a good example by @shayanhabibi of why this kind of interactions should be encouraged

[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.

[haxscramper]

Can I transfer this issue to the main repo, and convert it to discussion, similar to the thread for testament?

[saem]

@disruptek do you have permissions to move this issue to nimskull?

[disruptek]

If you cannot do it, I don't think I can do it. You're an Admin of nimskull AFAIK.

[haxscramper]

Alright, so you can move between public and private. This issue's discussion is superseded by #106 and probably best continue here since it is not an actionable target but rather an open-ended discussion about process improvements.