rust-lang / rust-lang/reference

Guidelines for linking to other documentation

Open
#2,039 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Authoring guide Meta
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.