rust-lang / rust-lang/reference
Guidelines for linking to other documentation
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.6k
- Forks
- 607
- PR merge metrics
- PR metrics pending
Description
I think the authoring guide should have guidelines for linking to external documentation.
There are some resources that could be useful to typical Rust developers, like TRPL, or other books or guides. However, having lots of links can be noisy.
There are also non-Rust references, which might be relevant (like other standards). But where do you draw the line?
What is the policy for linking to historical information, such as RFCs, PRs, GitHub issues, blog posts, etc? These sources are mostly static and not updated, and thus may provide outdated or incorrect information. However, as historical context they are useful.
- ehuss's preference: Don't ever link to RFCs, PRs, GitHub issues, blog posts, and similar things. However, we inevitably will hit sticky issues where we know something is wrong, and not linking to the relevant issue is withholding useful information.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the authoring guide and the examples of external and historical references described in this issue. Define a policy for linking to external documentation, non-Rust references, RFCs, pull requests, issues, and blog posts, then update the authoring guide once the policy is agreed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100