Description
Workflow criteria
An efficient workflow must satisfy one of two criteria:
- Determinism: the change of success per attempt is high.
- Iteration Speed: the frequency of attempts is high.
Composing links in documentation does not currently satisfy either of these criteria. The rules for linking are mysterious enough that a contributor cannot be confident that they will work without running make docs.
Examples of pain
#32130: a struct can be viewed from two locations, at varying depths of links; sometimes links to methods refer to the wrong modules.
#35880: doc entities are replicated between std and core.
#35759: directory links are confusing; anchors are case sensitive and do not match rendered content.
#rust-docs logs: Linkchecker is not always reliable (or potentially has usability problems).
#rust-docs logs: If a URL is present in both item description and short description, in the second case it won't work.
Potential resolutions
My hope is that this problem is procedural. It's entirely likely that I'm just wrong! If that's the case, then this issue can be resolved with documentation that either: 1) specifies a fast way to programmatically check docs locally, or 2) specifies a deterministic set of rules (a checklist) that allows a contributor to verify that their links will be successful without compiling them.
If I'm not wrong, then the problem becomes more difficult, which is why I created this issue. I appreciate any insight from more experienced members of the community.