Link to documentation-specific guidelines. #77195

follower · 2020-09-25T16:07:39Z

Changed contribution information URL because it's not obvious how to get from the current URL to the documentation-specific content.

The current URL points to this "Getting Started" page, which contains nothing specific about documentation[*] and instead launches into how to build rustc which is not a strict prerequisite for contributing documentation fixes:

https://rustc-dev-guide.rust-lang.org/getting-started.html

[*] The most specific content is a "Writing documentation" bullet point which is not itself a link to anything (I guess a patch for that might be helpful too).

Why?

Making this change will make it easier for people who wish to make small "drive by" documentation fixes (and read contribution guidelines ;) ) which I find are often how I start contributing to a project. (Exhibit A: #77050 :) )

Background

My impression is the change of content linked is an unintentional change due to a couple of other changes:

Originally, the link pointed to contributing.md which started with a "table of contents" linking to each section. But the content in contributing.md was removed and replaced with a link to the "Getting Started" section here:
- 3f6928f#diff-6a3371457528722a734f3c51d9238c13L1
But the changed link doesn't actually point to the equivalent content, which is now located here:
- https://rustc-dev-guide.rust-lang.org/contributing.html
(If the "Guide to Rustc Development" is now considered the canonical location of "How to Contribute" content it might be a good idea to merge some of the "Contributing" Introduction section into the "Getting Started" section.)
This was then compounded by changing the link from contributing.md to contributing.html here:
- https://github.com/rust-lang/rust/pull/74037/files#diff-242481015141f373dcb178e93cffa850L88
In order to even find the new location of the previous contributing.md content I ended up needing to do a GitHub search of the rust-lang org for the phrase "Documentation improvements are very welcome". :D

Changed because it's not obvious how to get from the previously used URL to the documentation-specific content. This is partly because the original URL was previously changed to point to different content: * https://github.com/rust-lang/rust/pull/74037/files#diff-242481015141f373dcb178e93cffa850L88 * rust-lang@3f6928f#diff-6a3371457528722a734f3c51d9238c13L12

rust-highfive · 2020-09-25T16:07:42Z

r? @kennytm

(rust_highfive has picked a reviewer for you, use r? to override)

pickfire · 2020-09-25T16:20:22Z

library/std/src/lib.rs

@@ -85,7 +85,7 @@
 //! # Contributing changes to the documentation
 //!
 //! Check out the rust contribution guidelines [here](
-//! https://rustc-dev-guide.rust-lang.org/getting-started.html).
+//! https://rustc-dev-guide.rust-lang.org/contributing.html#writing-documentation).
 //! The source for this documentation can be found on
 //! [GitHub](https://github.com/rust-lang/rust).


This doesn't seem specific, should we change this too?

Are you referring to the [GitHub](https://github.com/rust-lang/rust) link?

If so, yeah, I was working toward suggesting a PR for that too but it was a bit less "obvious" fix so was limiting this PR to just the one change.

The main question/issue I see is that the "Writing Documentation" section includes this sentence:

The source of doc.rust-lang.org is located in src/doc in the tree, and standard API documentation is generated from the source code itself.

So, depending on what "this documentation" is intended to refer to it's unclear whether the best approach is:

Link to library/std/src/lib.rs

Remove "The source for this documentation..." sentence entirely.

Replace "The source for this documentation..." sentence with "The source of doc.rust-lang.org is located in src/doc in the tree, and standard API documentation is generated from the source code itself (e.g. lib.rs)." (And/or make the link additions to https://rustc-dev-guide.rust-lang.org/contributing.html.)

I think you could just include another suggestion here along with the patch. But I think linking to library/std/src/lib.rs isn't good enough since people may want to edit other files.

I've put a PR in the dev guide repo with option 3: rust-lang/rustc-dev-guide#898

If that PR gets merged then perhaps we can decide if there's an issue with duplicating the content here?

The example link to library/std/src/lib.rs was (a) the literal source for the documentation in question :) and (b) just intended as an example to help people start looking in the right place. Open to other suggestions of where to link instead.

Adding multiple commits to a PR via the GitHub interface (as I'm currently doing for such "drive-by" contributions) is complicated due to the inability to--if I recall correctly--squash commits as required by Rust? (Or maybe that's a per-repo configuration setting?) So, if it's possible to just fix the one issue in this PR, that would be preferable on my part. :)

Adding multiple commits to a PR via the GitHub interface (as I'm currently doing for such "drive-by" contributions) is complicated due to the inability to--if I recall correctly--squash commits as required by Rust?

See also rust-lang/triagebot#821

So, if it's possible to just fix the one issue in this PR, that would be preferable on my part

I think it makes sense to have the changes in one place so it's easier to find all the discussion. I won't block on squashing the commits :)

Approach A

Based on the now merged #898, one possible approach is something like:

Suggested change

//! [GitHub](https://github.com/rust-lang/rust).

//! [GitHub](https://github.com/rust-lang/rust).

//! Standard API documentation is generated from

//! the source code itself (e.g. [`lib.rs`]) and the

//! source of `doc.rust-lang.org` is located in [`src/doc`] in the tree.

//!

//! [`lib.rs`]: https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1

//! [`src/doc`]: https://github.com/rust-lang/rust/tree/master/src/doc

But if this file is being viewed via https://doc.rust-lang.org/std/index.html#contributing-changes-to-the-documentation then that wording seems potentially confusing?

Approach B

An alternate wording:

This document and other Standard API documentation is generated from the source code itself (e.g. lib.rs) which can be found in library/ on GitHub.

Source for other documentation hosted on doc.rust-lang.org is located in src/doc.

(Given the content of the latter paragraph is now already mentioned elsewhere, I'm not sure that it's necessarily justified to mention it here.)

But if this file is being viewed via https://doc.rust-lang.org/std/index.html#contributing-changes-to-the-documentation then that wording seems potentially confusing?

Hmm, that doesn't seem too confusing to me: It says the documentation for the standard library lives in the source code for the standard library. I think lib.rs is a little confusing though, maybe say library/std instead.

Both of your approaches seem fine to me, I think both are more clear than the current links.

follower · 2020-09-25T17:00:13Z

As a side observation, it seems like the PRs related to these issues are a contributing factor to the underlying issue of what needs to be mentioned/linked where:

Make CONTRIBUTING.md into a series of tutorials compiler-team#296
Move CONTRIBUTING.md to rustc-dev-guide and instead point to Getting Started compiler-team#320

jyn514 · 2020-09-26T16:20:55Z

cc @steveklabnik @spastorino

jyn514 · 2020-10-10T15:26:30Z

@bors r+ rollup

Your current changes are good and I don't want to block them on doing a larger refactor. Please mention this PR in any follow-ups, though :)

bors · 2020-10-10T15:26:32Z

📌 Commit e4943ac has been approved by jyn514

Link to documentation-specific guidelines. Changed contribution information URL because it's not obvious how to get from the current URL to the documentation-specific content. The current URL points to this "Getting Started" page, which contains nothing specific about documentation[*] and instead launches into how to *build* `rustc` which is not a strict prerequisite for contributing documentation fixes: * https://rustc-dev-guide.rust-lang.org/getting-started.html [*] The most specific content is a "Writing documentation" bullet point which is not itself a link to anything (I guess a patch for that might be helpful too). ### Why? Making this change will make it easier for people who wish to make small "drive by" documentation fixes (and read contribution guidelines ;) ) which I find are often how I start contributing to a project. (Exhibit A: rust-lang#77050 :) ) ### Background My impression is the change of content linked is an unintentional change due to a couple of other changes: * Originally, the link pointed to `contributing.md` which started with a "table of contents" linking to each section. But the content in `contributing.md` was removed and replaced with a link to the "Getting Started" section here: * rust-lang@3f6928f#diff-6a3371457528722a734f3c51d9238c13L1 But the changed link doesn't actually point to the equivalent content, which is now located here: * https://rustc-dev-guide.rust-lang.org/contributing.html (If the "Guide to Rustc Development" is now considered the canonical location of "How to Contribute" content it might be a good idea to merge some of the "Contributing" Introduction section into the "Getting Started" section.) * This was then compounded by changing the link from `contributing.md` to `contributing.html` here: * https://github.com/rust-lang/rust/pull/74037/files#diff-242481015141f373dcb178e93cffa850L88 In order to even find the new location of the previous `contributing.md` content I ended up needing to do a GitHub search of the `rust-lang` org for the phrase "Documentation improvements are very welcome". :D

Rollup of 10 pull requests Successful merges: - rust-lang#77195 (Link to documentation-specific guidelines.) - rust-lang#77629 (Cleanup of `eat_while()` in lexer) - rust-lang#77709 (Link Vec leak doc to Box) - rust-lang#77738 (fix __rust_alloc_error_handler comment) - rust-lang#77748 (Dead code cleanup in windows-gnu std) - rust-lang#77754 (Add TraitDef::find_map_relevant_impl) - rust-lang#77766 (Clarify the debug-related values should take boolean) - rust-lang#77777 (doc: disambiguate stat in MetadataExt::as_raw_stat) - rust-lang#77782 (Fix typo in error code description) - rust-lang#77787 (Update `changelog-seen` in config.toml.example) Failed merges: r? `@ghost`

follower · 2020-10-19T19:25:52Z

@jyn514 Thanks! Yeah, real life caught up with me so I haven't gotten back to this. :)

rust-highfive assigned kennytm Sep 25, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 25, 2020

pickfire reviewed Sep 25, 2020

View reviewed changes

follower mentioned this pull request Sep 25, 2020

Make contributing.md into a series of tutorials rust-lang/rustc-dev-guide#775

Open

jyn514 added A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools labels Sep 25, 2020

This was referenced Sep 26, 2020

Could CONTRIBUTING.md be improved? #77215

Closed

Add link from "Writing Documentation" suggestion rust-lang/rustc-dev-guide#897

Merged

Add links to documentation sources. rust-lang/rustc-dev-guide#898

Merged

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 10, 2020

JohnTitor mentioned this pull request Oct 10, 2020

Rollup of 10 pull requests #77797

Closed

JohnTitor mentioned this pull request Oct 10, 2020

Rollup of 10 pull requests #77798

Merged

bors merged commit 1b13443 into rust-lang:master Oct 10, 2020

rustbot added this to the 1.49.0 milestone Oct 10, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Link to documentation-specific guidelines. #77195

Link to documentation-specific guidelines. #77195

follower commented Sep 25, 2020

rust-highfive commented Sep 25, 2020

pickfire Sep 25, 2020

follower Sep 25, 2020

pickfire Sep 26, 2020

follower Sep 26, 2020

jyn514 Sep 26, 2020

jyn514 Sep 26, 2020

follower Sep 27, 2020

jyn514 Sep 27, 2020

follower commented Sep 25, 2020

jyn514 commented Sep 26, 2020

jyn514 commented Oct 10, 2020

bors commented Oct 10, 2020

follower commented Oct 19, 2020

-//! [GitHub](https://github.com/rust-lang/rust).
+//! [GitHub](https://github.com/rust-lang/rust).
+//! Standard API documentation is generated from
+//! the source code itself (e.g. [`lib.rs`]) and the
+//! source of `doc.rust-lang.org` is located in [`src/doc`] in the tree.
+//!
+//! [`lib.rs`]: https://github.com/rust-lang/rust/blob/master/library/std/src/lib.rs#L1
+//! [`src/doc`]: https://github.com/rust-lang/rust/tree/master/src/doc

Link to documentation-specific guidelines. #77195

Link to documentation-specific guidelines. #77195

Conversation

follower commented Sep 25, 2020

Why?

Background

rust-highfive commented Sep 25, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Approach A

Approach B

Choose a reason for hiding this comment

follower commented Sep 25, 2020

jyn514 commented Sep 26, 2020

jyn514 commented Oct 10, 2020

bors commented Oct 10, 2020

follower commented Oct 19, 2020