Add guidelines about writing documentation #35

GuillaumeGomez · 2022-05-30T13:30:29Z

There are no guidelines on how to write documentation for std/core or how to review documentation updates. This PR is about adding the basics for this.

GuillaumeGomez · 2022-05-30T13:48:28Z

I'm not sure who to ping here so ping @m-ou-se since it's about libs API docs. :)

src/documentation/how-to-write-documentation.md

src/documentation/reviewing-doc-changes.md

src/documentation/how-to-write-documentation.md

src/documentation/reviewing-doc-changes.md

GuillaumeGomez · 2022-05-30T21:49:49Z

I applied all your suggestions @yaahc, thanks a lot!

src/documentation/how-to-write-documentation.md

GuillaumeGomez · 2022-05-31T12:00:43Z

Updated!

generated from commit f513a22

m-ou-se · 2022-06-01T13:30:03Z

src/documentation/how-to-write-documentation.md

+It is common in English to have contractions such as "don't" or "can't". Do not
+use these in documentation. Always write their "full form":
+
+ * "do not" instead of "don't"
+ * "cannot" instead of "can't"
+ * "it would" instead of "it'd"
+ * "it will" instead of "it'll"
+ * "it is"/"it has" instead of "it's"
+ * "you are" instead of "you're"
+ * "they are" instead of "they're"


Why? We currently have over 600 of such contractions in doc comments in library/*.

I think it's definitely good to have guidelines, but we should probably start with writing down the existing practices rather than making new rules that we currently don't follow.

I think the explanations I provided below provide explanations for it. Making documentation easier to read by reducing congestion like trying to figure out if 'd is "had" or "should/would" doesn't seem like a bad idea. Until now we didn't have a guideline so it was to be expected. I don't see why it'd be an issue when writing new documentation though. Nothing prevents us to slowly update the existing documentation.

But maybe you had some other reasons?

I'll point out: while there is no such thing as "standardized" english, only some of these contractions are found in formal usage (don't, can't, it'll, it's, you're, they're are found, whereas 'd for should/would/had is not as much), and I cannot think of a single English contraction that is ambiguous in formal usage (e.g. your example about 'd doesn't apply at all). Folks are more loose in chats/etc, but most modern English style guides allow contractions, and if anything it reads weirdly if you omit them. Discouraging contractions seems rather weird.

I think I followed what the rustc errors do (which disallow contractions). Maybe I'm once again imagining things...

m-ou-se · 2022-06-01T13:31:32Z

src/documentation/how-to-write-documentation.md

+### Examples
+
+As for the examples, they have to show the usage of the function/method. Just
+like the `panic` section, they need to be prepended by a `Examples` title.


In many cases we just have # Example (singular) instead of # Examples when there's only one example.

I don't remember the debate behind this (I think @Manishearth was involved in this debate? Please correct me if I'm wrong!) but it's what we already recommend in the rustdoc book. I'm fine with updating both though if needed.

I don't remember being involved in this debate at all. I think both are fine.

I recall making sure the clippy lint for this can detect both (or at least talking about that).

Then it was maybe at the time when the documentation team still existed I guess... Like said above, I'm fine with both.

m-ou-se · 2022-06-01T13:42:06Z

src/documentation/how-to-write-documentation.md

+Little note: when you are documenting an item, no need to link to it. So if you
+write documentation for `String::push_str` method, no need to link to the method
+`push_str` or to the `String` type.


This paragraph seems to be missing a few words.

Suggested change

Little note: when you are documenting an item, no need to link to it. So if you

write documentation for `String::push_str` method, no need to link to the method

`push_str` or to the `String` type.

Little note: when you are documenting an item, there is no need to link to it.

So, if you write documentation for the `String::push_str` method, there is

no need to link to the `push_str` method or the `String` type.

m-ou-se · 2022-06-01T13:43:01Z

src/documentation/how-to-write-documentation.md

+If you have cases like `Vec<String>`, you need to use intra-doc links on both
+`Vec` and `String` as well. It would look like this:
+
+```text
+This is a [`Vec`]`<`[`String`]`>`.
+```


This is something we currently rarely do, and I'm not sure we should do that everywhere, as it's quite tedious with not a lot of benefit.

It makes the reading better. As such, I think it's a good enough reason.

(It's also something we enforced when the documentation team still existed too)

It makes the reading better.

It don't think it does. It just adds more noise with the changes in color/formatting.

If both A and B are very relevant, then it might make sense to link them separately in A<B>. But quite often B isn't very relevant, and it's fine and less noisy to just link all of A<B> to A.

Regardless, this is guideline is not uncontroversial. It's fine to document and merge guidelines in to std-dev-guide that we already follow, by documenting existing practice. But new rules that we don't currently follow should first have some discussion and a decision.

Right now, we have exactly one doc comment that uses the syntax [..]`<`[..]`>`.

You're absolutely right. I remembered that we had a lot more around. I guess my memory about it is completely outdated...

I still appreciate to be able to click on each type separately but maybe it's only me...

m-ou-se · 2022-06-01T13:44:59Z

src/documentation/how-to-write-documentation.md

+This is a [`Vec`]`<`[`String`]`>`.
+```
+
+Extra explanations: since both `Vec` and `String` are in codeblocks, `<` and `>`


"explanation" is usually used a an uncountable noun, with no separate plural form:

Suggested change

Extra explanations: since both `Vec` and `String` are in codeblocks, `<` and `>`

Extra explanation: since both `Vec` and `String` are in codeblocks, `<` and `>`

TIL, thanks!

Wikipedia seems to say it's countable: https://simple.wiktionary.org/wiki/explanation whereas oxford dictionary says it's both: https://www.oxfordlearnersdictionaries.com/definition/english/explanation 😆

It can be countable, however that usually applies to when, e.g. you're doing multiple explanations to different people or at different times. If it's being explained in one place, that's a single explanation even if it has multiple parts.

(this is similar to how "fish" is uncountable except when talking about different kinds of fish)

Tricky language. Thanks for the explanation!

GuillaumeGomez force-pushed the writing-docs branch from acdd300 to cebddfa Compare May 30, 2022 13:32

GuillaumeGomez force-pushed the writing-docs branch from cebddfa to e5ebb88 Compare May 30, 2022 15:05

JohnTitor reviewed May 30, 2022

View reviewed changes