Minor English fixes/improvements

Cherry-pick of #29370.

Author: mark-summerfield

doc/src/manual/documentation.md

@@ -3,10 +3,10 @@
 Julia enables package developers and users to document functions, types and other objects easily
 via a built-in documentation system since Julia 0.4.
 
-The basic syntax is simple: any string appearing at the top-level right before an object
-(function, macro, type or instance) will be interpreted as documenting it (these are called *docstrings*).
-Note that no blank lines or comments may intervene between a docstring and the documented object.
-Here is a basic example:
+The basic syntax is simple: any string appearing at the toplevel right before an object
+(function, macro, type or instance) will be interpreted as documenting it (these are called
+*docstrings*). Note that no blank lines or comments may intervene between a docstring and
+the documented object. Here is a basic example:
 
 ```julia
 "Tell whether there are too foo items in the array."
@@ -187,16 +187,16 @@ As in the example above, we recommend following some simple conventions when wri
    f(x, y) = ...
    ```
 
-   This makes it more clear where docstrings start and end.
+   This makes it clearer where docstrings start and end.
 9. Respect the line length limit used in the surrounding code.
 
    Docstrings are edited using the same tools as code. Therefore, the same conventions should apply.
-   It is advised to add line breaks after 92 characters.
+   It is recommended that lines are at most 92 characters wide.
 6. Provide information allowing custom types to implement the function in an
-   `# Implementation` section. These implementation details intended for developers
-   rather than users, explaining e.g. which functions should be overridden and which functions
-   automatically use appropriate fallbacks, are better kept separate from the main description of
-   the function's behavior.
+   `# Implementation` section. These implementation details are intended for developers
+   rather than users, explaining e.g. which functions should be overridden and which
+   functions automatically use appropriate fallbacks. Such details are best kept separate
+   from the main description of the function's behavior.
 
 ## Accessing Documentation
 
@@ -209,8 +209,9 @@ by typing `?` followed by the name of a function or macro, and pressing `Enter`.
 ?r""
 ```
 
-will bring up docs for the relevant function, macro or string macro respectively. In [Juno](http://junolab.org)
-using `Ctrl-J, Ctrl-D` will bring up documentation for the object under the cursor.
+will show documentation for the relevant function, macro or string macro respectively. In
+[Juno](http://junolab.org) using `Ctrl-J, Ctrl-D` will show the documentation for the object
+under the cursor.
 
 ## Functions & Methods
 
@@ -335,6 +336,7 @@ y = MyType("y")
 ## Syntax Guide
 
 A comprehensive overview of all documentable Julia syntax.
+
 In the following examples `"..."` is used to illustrate an arbitrary docstring.
 
 ### `$` and `\` characters
@@ -520,8 +522,8 @@ the referenced value itself.
 sym
 ```
 
-Adds docstring `"..."` to the value associated with `sym`. Users should prefer documenting `sym`
-at its definition.
+Adds docstring `"..."` to the value associated with `sym`. However, it is preferred that
+`sym` is documented where it is defined.
 
 ### Multiple Objects
 
@@ -551,9 +553,9 @@ two functions are related, such as non-mutating and mutating versions `f` and `f
 @m expression
 ```
 
-Adds docstring `"..."` to expression generated by expanding `@m expression`. This allows for expressions
-decorated with `@inline`, `@noinline`, `@generated`, or any other macro to be documented in the
-same way as undecorated expressions.
+Adds docstring `"..."` to the expression generated by expanding `@m expression`. This allows
+for expressions decorated with `@inline`, `@noinline`, `@generated`, or any other macro to
+be documented in the same way as undecorated expressions.
 
 Macro authors should take note that only macros that generate a single expression will automatically
 support docstrings. If a macro returns a block containing multiple subexpressions then the subexpression

stdlib/Markdown/docs/src/index.md

@@ -40,7 +40,7 @@ parts of a Julia program.
     the text.
 
     ```
-    A paragraph containing a ``` `backtick` character ```.
+    A paragraph containing ``` `backtick` characters ```.
     ```
 
     By extension any odd number of backticks may be used to enclose a lesser number of backticks.
@@ -70,7 +70,7 @@ A paragraph containing some ``\LaTeX`` markup.
 
 ### Links
 
-Links to either external or internal addresses can be written using the following syntax, where
+Links to either external or internal targets can be written using the following syntax, where
 the text enclosed in square brackets, `[ ]`, is the name of the link and the text enclosed in
 parentheses, `( )`, is the URL.
 
@@ -127,7 +127,7 @@ in the [Inline elements](@ref) section above, with one or more blank lines above
 ```
 This is a paragraph.
 
-And this is *another* one containing some emphasized text.
+And this is *another* paragraph containing some emphasized text.
 A new line, but still part of the same paragraph.
 ```
 
@@ -316,7 +316,8 @@ aside from the `:` character that is appended to the footnote label.
 
 ### Horizontal rules
 
-The equivalent of an `<hr>` HTML tag can be written using the following syntax:
+The equivalent of an `<hr>` HTML tag can be achieved using three hyphens (`---`).
+For example:
 
 ```
 Text above the line.