Let's have a "documentation policy"?


#1

The only semblance of Rust documentation policy/guidelines can be found in src/book/documentation.md, which I think should be moved elsewhere, perhaps to Style guidelines or own file. The chapter can remain in the book, but should only explain how stuff is done, not mandate policy (e.g. “The first line of a documentation comment should be a short summary of its functionality”).

One other thing: if we do create documentation policy/guidelines, should it be universal to Rust projects, or just the rust-lang/rust? I suggest we create “Documentation Guidelines”, either as a stand-alone document or as a chapter of “Style Guidelines” document, and have contributions to rust-lang/rust documentation follow those guidelines.


#2

Not to be a downer, but there has been a great rush to institute new ‘policy’ lately, and it’s kind of grinding on me. Maybe we can focus on writing software for a while and not doing politics.


#3

Would this be in the scope of the Community team?


#4

This isn’t strictly true, we have an accepted RFC: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md

Ideally, we’d come up with these guidelines, but until we have enough people doing lots of docs to make a documentaiton team, I don’t think that it’s worth it to do more. These kinds of RFCs are high, high, high effort.


#5

Are you talking about the Stability discussions?


#6

I actually forgot about that document, thanks.


#7

Do we prefer plain or curly quotes in the text of the API documentation in Rust (rust-lang/rust itself)?