1 files changed, 153 insertions, 38 deletions
diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md
index f011841809..59953d0d52 100644
--- a/doc/contributing/documentation_guide.md
+++ b/doc/contributing/documentation_guide.md
@@ -20,14 +20,16 @@ build directory:
 make html
 ```
 
+If you don't have a build directory, follow the [quick start
+guide](building_ruby.md#label-Quick+start+guide) up to step 4.
+
 Then you can preview your changes by opening
 `{build folder}/.ext/html/index.html` file in your browser.
 
-
 ## Goal
 
 The goal of Ruby documentation is to impart the most important
-and relevant in the shortest time.
+and relevant information in the shortest time.
 The reader should be able to quickly understand the usefulness
 of the subject code and how to use it.
 
@@ -41,16 +43,17 @@ Use your judgment about what the user needs to know.
 - Write short declarative or imperative sentences.
 - Group sentences into (ideally short) paragraphs,
   each covering a single topic.
-- Organize material with [headers](rdoc-ref:RDoc::Markup@Headers).
+- Organize material with
+  [headings](rdoc-ref:RDoc::MarkupReference@Headings).
 - Refer to authoritative and relevant sources using
-  [links](rdoc-ref:RDoc::Markup@Links).
+  [links](rdoc-ref:RDoc::MarkupReference@Links).
 - Use simple verb tenses: simple present, simple past, simple future.
 - Use simple sentence structure, not compound or complex structure.
 - Avoid:
     - Excessive comma-separated phrases;
-      consider a [list](rdoc-ref:RDoc::Markup@Simple+Lists).
+      consider a [list](rdoc-ref:RDoc::MarkupReference@Lists).
     - Idioms and culture-specific references.
-    - Overuse of headers.
+    - Overuse of headings.
     - Using US-ASCII-incompatible characters in C source files;
       see [Characters](#label-Characters) below.
 
@@ -124,32 +127,136 @@ a.shuffle!    #=> [2, 3, 1]
 a             #=> [2, 3, 1]
 ```
 
-### Headers
+### Headings
+
+Organize a long discussion for a class or module with [headings](rdoc-ref:RDoc::MarkupReference@Headings).
 
-Organize a long discussion with [headers](rdoc-ref:RDoc::Markup@Headers).
+Do not use formal headings in the documentation for a method or constant.
+
+In the rare case where heading-like structures are needed
+within the documentation for a method or constant, use
+[bold text](rdoc-ref:RDoc::MarkupReference@Bold)
+as pseudo-headings.
 
 ### Blank Lines
 
 A blank line begins a new paragraph.
 
-A [code block](rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim)
-or [list](rdoc-ref:RDoc::Markup@Simple+Lists)
+A [code block](rdoc-ref:RDoc::MarkupReference@Code+Blocks)
+or [list](rdoc-ref:RDoc::MarkupReference@Lists)
 should be preceded by and followed by a blank line.
 This is unnecessary for the HTML output, but helps in the `ri` output.
 
+### \Method Names
+
+For a method name in text:
+
+- For a method in the current class or module,
+  use a double-colon for a singleton method,
+  or a hash mark for an instance method:
+  <tt>::bar</tt>, <tt>#baz</tt>.
+- Otherwise, include the class or module name
+  and use a dot for a singleton method,
+  or a hash mark for an instance method:
+  <tt>Foo.bar</tt>, <tt>Foo#baz</tt>.
+
+### Embedded Code and Commands
+
+Code or commands embedded in running text (i.e., not in a code block)
+should marked up as
+[monofont](rdoc-ref:RDoc::MarkupReference@Monofont).
+
+Code that is a simple string should include the quote marks.
+
 ### Auto-Linking
 
 In general, \RDoc's auto-linking should not be suppressed.
 For example, we should write `Array`, not `\Array`.
 
-We might consider whether to suppress when:
+However, suppress when the word in question:
 
-- The word in question does not refer to a Ruby entity
+- Does not refer to a Ruby entity
   (e.g., some uses of _Class_ or _English_).
-- The reference is to the current class document
-  (e.g., _Array_ in the documentation for class `Array`).
-- The same reference is repeated many times
-  (e.g., _RDoc_ on this page).
+- Refers to the current document
+  (e.g., _Array_ in the documentation for class `Array`);
+  in that case, the word should be forced to
+  [monofont](rdoc-ref:RDoc::MarkupReference@Monofont).
+
+Most often, the name of a class, module, or method
+will be auto-linked:
+
+- Array.
+- Enumerable.
+- File.new
+- File#read.
+
+If not, or if you suppress autolinking, consider forcing
+[monofont](rdoc-ref:RDoc::MarkupReference@Monofont).
+
+### Explicit Links
+
+When writing an explicit link, follow these guidelines.
+
+#### +rdoc-ref+ Scheme
+
+Use the +rdoc-ref+ scheme for:
+
+- A link in core documentation to other core documentation.
+- A link in core documentation to documentation in a standard library package.
+- A link in a standard library package to other documentation in that same
+  standard library package.
+
+See section "+rdoc-ref+ Scheme" in {Links}[rdoc-ref:RDoc::MarkupReference@Links].
+
+#### URL-Based Link
+
+Use a full URL-based link for:
+
+- A link in standard library documentation to documentation in the core.
+- A link in standard library documentation to documentation in a different
+  standard library package.
+
+Doing so ensures that the link will valid even when the package documentation
+is built independently (separately from the core documentation).
+
+The link should lead to a target in https://docs.ruby-lang.org/en/master/.
+
+Also use a full URL-based link for a link to an off-site document.
+
+### Variable Names
+
+The name of a variable (as specified in its call-seq) should be marked up as
+[monofont](rdoc-ref:RDoc::MarkupReference@Monofont).
+
+Also, use monofont text for the name of a transient variable
+(i.e., one defined and used only in the discussion, such as +n+).
+
+### HTML Tags
+
+In general, avoid using HTML tags (even in formats where it's allowed)
+because `ri` (the Ruby Interactive reference tool)
+may not render them properly.
+
+### Tables
+
+In particular, avoid building tables with HTML tags
+(<tt><table></tt>, etc.).
+
+Alternatives:
+
+- A {verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks],
+  using spaces and punctuation to format the text;
+  note that {text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup]
+  will not be honored:
+
+    - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/file.c#L6570-L6596].
+    - Corresponding {output}[rdoc-ref:File@Read-2FWrite+Mode].
+
+- (Markdown format only): A {Github Flavored Markdown (GFM) table}[https://github.github.com/gfm/#tables-extension-],
+  using special formatting for the text:
+
+    - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/doc/contributing/glossary.md?plain=1].
+    - Corresponding {output}[https://docs.ruby-lang.org/en/master/contributing/glossary_md.html].
 
 ## Documenting Classes and Modules
 
@@ -179,9 +286,12 @@ Guidelines:
 
 - The section title is `What's Here`.
 - Consider listing the parent class and any included modules; consider
-  [links](rdoc-ref:RDoc::Markup@Links)
+  [links](rdoc-ref:RDoc::MarkupReference@Links)
   to their "What's Here" sections if those exist.
-- List methods as a bullet list:
+- All methods mentioned in the left-pane table of contents
+  should be listed (including any methods extended from another class).
+- Attributes (which are not included in the TOC) may also be listed.
+- Display methods as items in one or more bullet lists:
 
     - Begin each item with the method name, followed by a colon
       and a short description.
@@ -189,9 +299,9 @@ Guidelines:
       (and do not list the aliases separately).
     - Check the rendered documentation to determine whether \RDoc has recognized
       the method and linked to it;  if not, manually insert a
-      [link](rdoc-ref:RDoc::Markup@Links).
+      [link](rdoc-ref:RDoc::MarkupReference@Links).
 
-- If there are numerous entries, consider grouping them into subsections with headers.
+- If there are numerous entries, consider grouping them into subsections with headings.
 - If there are more than a few such subsections,
   consider adding a table of contents just below the main section title.
 
@@ -206,7 +316,6 @@ The general structure of the method documentation should be:
 - Details and examples.
 - Argument description (if necessary).
 - Corner cases and exceptions.
-- Aliases.
 - Related methods (optional).
 
 ### Calling Sequence (for methods written in C)
@@ -215,7 +324,7 @@ For methods written in Ruby, \RDoc documents the calling sequence automatically.
 
 For methods written in C, \RDoc cannot determine what arguments
 the method accepts, so those need to be documented using \RDoc directive
-[`call-seq:`](rdoc-ref:RDoc::Markup@Method+arguments).
+[`call-seq:`](rdoc-ref:RDoc::MarkupReference@Directives+for+Method+Documentation).
 
 For a singleton method, use the form:
 
@@ -293,7 +402,11 @@ Return types:
 
 Aliases:
 
-- Omit aliases from the `call-seq`, but mention them near the end (see below).
+- Omit aliases from the `call-seq`, unless the alias is an
+  operator method. If listing both a regular method and an
+  operator method in the `call-seq`, explain in the details and
+  examples section when it is recommended to use the regular method
+  and when it is recommended to use the operator method.
 
 ### Synopsis
 
@@ -350,7 +463,7 @@ argument passed if it is not obvious, not explicitly mentioned in the
 details, and not implicitly shown in the examples.
 
 If there is more than one argument or block argument, use a
-[labeled list](rdoc-ref:RDoc::Markup@Labeled+Lists).
+[labeled list](rdoc-ref:RDoc::MarkupReference@Labeled+Lists).
 
 ### Corner Cases and Exceptions
 
@@ -363,25 +476,27 @@ you do not need to document that a `TypeError` is raised if a non-integer
 is passed.  Do not provide examples of exceptions being raised unless
 that is a common case, such as `Hash#fetch` raising a `KeyError`.
 
-### Aliases
-
-Mention aliases in the form
-
-```
-// Array#find_index is an alias for Array#index.
-```
-
 ### Related Methods (optional)
 
 In some cases, it is useful to document which methods are related to
 the current method.  For example, documentation for `Hash#[]` might
 mention `Hash#fetch` as a related method, and `Hash#merge` might mention
-`Hash#merge!` as a related method.  Consider which methods may be related
-to the current method, and if you think the reader would benefit it,
-at the end of the method documentation, add a line starting with
-"Related: " (e.g. "Related: #fetch").  Don't list more than three
-related methods. If you think more than three methods are related,
-pick the three you think are most important and list those three.
+`Hash#merge!` as a related method.
+
+- Consider which methods may be related
+  to the current method, and if you think the reader would benefit it,
+  at the end of the method documentation, add a line starting with
+  "Related: " (e.g. "Related: #fetch.").
+- Don't list more than three related methods.
+  If you think more than three methods are related,
+  list the three you think are most important.
+- Consider adding:
+
+    - A phrase suggesting how the related method is similar to,
+      or different from,the current method.
+      See an example at Time#getutc.
+    - Example code that illustrates the similarities and differences.
+      See examples at Time#ctime, Time#inspect, Time#to_s.
 
 ### Methods Accepting Multiple Argument Types