Skip to content

Guidelines for linking to other documentation #2039

@ehuss

Description

@ehuss

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Authoring guideIssues for the authoring guide and style guidelinesMetaNon-content issues (procedure, tooling, website, etc.)

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions