Reviewing the technical writing docs

doc/contributors-guide/modules/ROOT/pages/coder/lexing-and-parsing.adoc

@@ -13,7 +13,7 @@ Each token has a type and a snippet of characters.
 The standard tool in IntelliJ is https://jflex.de[JFlex].
 
 The heart of lexing is `asciidoc.flex`.
-It defines multiple states, and uses a lot of functionalities and tweaking to parse AsciiDoc.
+It defines multiple states and uses a lot of functionalities and tweaking to parse AsciiDoc.
 Developers can add new token types in `AsciiDocTokenTypes`.
 Ensure to update the list `TOKENS_TO_MERGE` if consecutive identical types of the tokens should be merged.
 If the content of the token types should be spell-checked, add the token types to the list of tokens in `AsciiDocSpellcheckingStrategy`.
@@ -29,7 +29,7 @@ A typical developer workflow for enhancing the lexer looks like this:
 . Change `asciidoc.flex` in the IDE, adding new entries to `AsciiDocTokenTypes` as needed.
 . Run `gradlew compileJava` on the command line.
 . Add a test case to `AsciiDocLexerTest` and run it from the IDE.
-. If lexing does not yet work as expected repeat from step 1.
+. If lexing does not yet work as expected, repeat from step 1.
 . If lexing returns the expected result, update the `expected` parameter in the test.
 
 There is a ready-to-use run-configuration in Intellij called "`AsciiDocLexerTest`" that will re-generate the lexer and run the tests in one go.
@@ -45,7 +45,7 @@ If you get the syntax wrong, the converter usually prints the wrong syntax "`as
 Only a matching set of for example asterisks (`*`) produces bold text.
 --
 
-Here some JFlex rules for AsciiDoc together with an explanation:
+Here are some JFlex rules for AsciiDoc together with an explanation:
 
 Look ahead rules::
 +
@@ -65,7 +65,7 @@ End of line and end of file parsing::
 --
 JFlex supports `$` to describe the end of a line as look-ahead.
 But this doesn't work at the end of a file.
-To match the end of a file, the lexer uses the fact that JFlex will match the longest rule first (including any look-ahead rules).
+To match the end of a file, the lexer uses the fact that JFlex will match the longest rule first, including any look-ahead rules.
 So first match the end of a line, then when not at the end of a line with the same length, and then the end of the file (the shortest rule).
 
 .Example: matching a delimiter at the end of the file
@@ -85,7 +85,7 @@ So first match the end of a line, then when not at the end of a line with the sa
 Stateful parser::
 +
 --
-To parse bold, italic and monospace text (that can be nested) there is a set of boolean variables to memorize the current text style.
+To parse bold, italic and monospace text, which can be nested, there is a set of boolean variables to memorize the current text style.
 They are reset at the end of a block, like in a regular AsciiDoc file.
 The function `textFormat()` uses them to determine the current token type from a combination of these flags.
 
@@ -95,7 +95,7 @@ Other states memorize the length of block separator line to find the matching cl
 Qualifying matches, push back and state change::
 +
 --
-After a match the Java code checks additional conditions like if this is an unconstrained position in the stream.
+After a match, the Java code checks additional conditions like if this is an unconstrained position in the stream.
 If the code decides to discard the match, two possible strategies out of several are:
 
 . Push back all but the first character, and return the token type for the single character.
@@ -114,7 +114,7 @@ Auto-completion::
 +
 --
 Expressions described above match expressions once they have their closing syntax completed, and it is essential for the correct highlighting.
-To support autocomplete the matching must handle an expression where only the left part of the expression exists.
+To support autocomplete, the matching must handle an expression where only the left part of the expression exists.
 
 A special case is in the parser to support autocompletion, as IntelliJ inserts a special string when parsing the content for autocompletion (named `auto-complete` in our parser).
 
@@ -137,10 +137,10 @@ Highlighting is coloring the text in the editor.
 The file `AsciiDocSyntaxHighlighter` defines one `TextAttributesKey` to each entry in `AsciiDocTokenTypes` parsed during lexing.
 Currently, several tokens have the same highlighting `ASCIIDOC_MARKER`, so users have the same color for the pointy brackets around references (`\<<ref>>`)and markers for bold (`\*bold*`).
 
-Once you add a new `TextAttributesKey`, you should either:
+Once you add a new `TextAttributesKey`, either:
 
-. reference an existing color (like `ASCIIDOC_COMMENT` references `DefaultLanguageHighlighterColors.LINE_COMMENT`) OR
-. add a color the AsciiDoc themes `AsciidocDefault.xml` and `AsciidocDarcula.xml`
+. Reference an existing color (like `ASCIIDOC_COMMENT` references `DefaultLanguageHighlighterColors.LINE_COMMENT`).
+. Add a color the AsciiDoc themes `AsciidocDefault.xml` and `AsciidocDarcula.xml`.
 
 Once you add a new token, you will need to add it to `AsciiDocColorSettingsPage` so users can customize the colors of their theme.
 This class references also `SampleDocument.adoc` and `AsciiDocBundle.properties`, therefore you'll probably need to change these two files as well.
@@ -184,7 +184,7 @@ To support this `TITLE` and several other elements call `markPreBlock()` to memo
 It is stored in a variable `myPreBlockMarker`.
 
 When parsing of the block starts and the `myPreBlockMarker` is set, it uses this marker.
-If the marker is not set, is creates a new marker at the start of the block delimiter.
+If the marker is not set, it creates a new marker at the start of the block delimiter.
 When the block doesn't start on one of the following lines, `dropPreBlock()` drops the marker.
 --
 
@@ -222,7 +222,7 @@ The tests come in two variants:
 AsciiDocPsiTest::
 +
 --
-This test parses a minimal snippet of AsciiDoc, creates the PSI tree, and the lets you apply assertions like in normal unit tests.
+This test parses a minimal snippet of AsciiDoc, creates the PSI tree, and allows for assertions like in normal unit tests.
 
 Use this to write specific tests.
 Consider a given/when/then structure to write tests that are comprehensible for other developers.
@@ -239,7 +239,7 @@ Then put a matching AsciiDoc file to the example file directory (like `sectionsW
 When you run the test for the first time, it will create a known good file (like `sectionsWithPreBlock.txt`).
 Check the contents of the known good file if the result matches your expectations.
 
-On consecutive runs the test will compare the parser result with the contents of the known good file.
+On consecutive runs, the test will compare the parser result with the contents of the known good file.
 If the content matches, the test will pass.
 If there are differences, the test will fail.
 If you expected these differences, for example, because you changed the parser or lexer, copy the result shown in your IDE to the known good file.
@@ -263,7 +263,7 @@ Writing such a test is often slower as it requires more code and skill, but it w
 
 === References and renaming
 
-All PsiElement that reference files (like for example an `include::[]`) or IDs (like for example `\<<id>>`) return references.
+All PsiElement that reference files like, for example, an `include::[]`, or IDs like, for example, an `+<<id>>+` return references.
 Examples for this are `AsciiDocBlockMacro` and `AsciiDocRef`.
 They all need to provide a `Manipulator` that IntelliJ calls when the user renames such a reference.
 To make the "`Find References`" functionality work, the tokens that contain the IDs need to be part of the Identifier-Token-Set in `AsciiDocWordsScanner`.

doc/users-guide/modules/ROOT/pages/technical-writing/editing-an-asciidoc-file.adoc

@@ -48,7 +48,7 @@ image::technical-writing/intellij-tool-windows.png[]
 
 . The project view is a tree view of all files in the project.
 Clicking on "`Project`" hides and shows this view.
-This is a functionality of all tool windows.
+This works with all tool windows.
 
 . The structure view displays the structure of the current AsciiDoc file in the editor.
 Clicking on "`Structure`" hides and shows this view.

doc/users-guide/modules/ROOT/pages/technical-writing/getting-help.adoc

@@ -14,7 +14,7 @@ There are different documentation sites for different topics:
 
 https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]::
 This is the reference documentation for the AsciiDoc language.
-Find out which macros exist, how to format tables, links, lists etc.
+Find out which macros exist, how to format tables, links, lists, etc.
 
 https://docs.asciidoctor.org/asciidoctor/latest/[Asciidoctor Documentation]::
 Learn about how to use the Asciidoctor implementation to convert AsciiDoc content to HTML and other formats on the command line or how to embed it into a build process.
@@ -38,14 +38,14 @@ The maintainers of Asciidoctor and the AsciiDoc plugin for IntelliJ are active i
 Still, getting answers to new questions might take some hours or days.
 
 https://asciidoctor.zulipchat.com/[Asciidoctor Zulip Chat]::
-This chat covers questions and answers around Asciidoctor, the open source implementation to turn AsciiDoc content into HTML, PDF, epub and other formats.
+This chat covers questions and answers around Asciidoctor, the open source implementation to turn AsciiDoc content into HTML, PDF, epub, and other formats.
 Go to https://asciidoctor.zulipchat.com/ to join the chat, and have a look at https://asciidoctor.org/ to find out more about the project.
 
 https://asciidoctor.zulipchat.com/[Antora Zulip Chat]::
 This chat covers questions and answers around Antora, the open source multi-repository documentation site generator for tech writers that is based on AsciiDoc.
 Go to https://antora.zulipchat.com/ to join the chat, and have a look at https://antora.org/ to find out more about the project.
 On the website, scroll down to find a high-level summary of the project's features.
-Click on menu:Docs[] in the upper right corner for an extensive documentation.
+Click on menu:Docs[] in the upper right corner for extensive documentation.
 
 https://asciidoc.zulipchat.com/[AsciiDoc Zulip Chat]::
 The AsciiDoc Working Group at Eclipse steers the future of the AsciiDoc Language.
@@ -71,7 +71,7 @@ On the other hand follow-up activities are better tracked on GitHub issues.
 The Write The Docs community provides a website for technical writers at https://www.writethedocs.org/, organizes conferences around the world which make their recordings available free of charge, and supports the community with a publicly available Slack channel.
 
 The Slack instance has many channels, for example #asciidoc, #static-site-generator and #docs-as-code.
-They might give additional insights, still the <<asciidoc-community-chats-on-zulip,Zulip chats mentioned above>> seem to be more active and more focused on AsciiDoc content at the time of writing.
+They might give additional insights, still the <<asciidoc-community-chats-on-zulip,Zulip chats mentioned above>> seem more active and more focused on AsciiDoc content at the time of writing.
 
 Use the chat to get answers to your questions, and help others with their questions.
 
@@ -81,7 +81,7 @@ The Write-the-Docs community offers local meetups.
 See https://www.writethedocs.org/meetups/ for a list.
 Join the Write-the-Docs Slack instance and watch the channel #meetups to see postings of upcoming meetings.
 
-There's also the Meetup https://www.meetup.com/continuous-documentation-regulars[Continuous Documentation Regulars] which is happens to be hosted by the maintainer of the AsciiDoc plugin.
+There's also the Meetup https://www.meetup.com/continuous-documentation-regulars[Continuous Documentation Regulars] which happens to be hosted by the maintainer of the AsciiDoc plugin.
 Expect topics around documentation as code in general, not necessarily focused on AsciiDoc only.
 
 == Further reading

doc/users-guide/modules/ROOT/pages/technical-writing/git-integration.adoc

@@ -21,9 +21,9 @@ To use the Git command line, choose the "`Terminal`" toolbox tab in IntelliJ to
 The following example assumes that:
 
 * The project is a checked-out remote repository.
-* The local repository has a remote "`upstream`" with points to the main repository where people collaborate around a branch "`main`".
-* The local repository has a remote "`origin`" with points to a clone of the main repository where the user wants to create a branch from where they want to create a pull request later.
-+ The currently checked out branch in the local repository is "`main`" and points to the remote "`origin`".
+* The local repository has a remote `upstream` with points to the main repository where people collaborate around a branch `main`.
+* The local repository has a remote `origin` with points to a clone of the main repository where the user wants to create a branch from where they want to create a pull request later.
+* The currently checked-out branch in the local repository is `main` and points to the remote `origin`.
 
 === Overview of the controls and tool windows
 
@@ -39,7 +39,7 @@ image::technical-writing/intellij-git.png[]
 Open it by click on the tool window or use the shortcut [.windows.linux]#kbd:[Alt+0]# [.macos]#kbd:[⌘ 0]#.
 Explore the different actions in the toolbar by hovering with the mouse over the different icons.
 +
-Double-click on a highlighted file or press [.windows.linux]#kbd:[Ctrl+D]# [.macos]#kbd:[⌘ D]# to show the differences side-by-side. See the IntelliJ documentation on how to https://www.jetbrains.com/help/idea/comparing-file-versions.html[Compare file and folder versions].
+Double-click on a highlighted file or press [.windows.linux]#kbd:[Ctrl+D]# [.macos]#kbd:[⌘ D]# to show the difference side-by-side. See the IntelliJ documentation on how to https://www.jetbrains.com/help/idea/comparing-file-versions.html[Compare file and folder versions].
 
 === Resolving merge conflicts
 

doc/users-guide/modules/ROOT/pages/technical-writing/index.adoc

@@ -22,7 +22,7 @@ Follow these steps to set up IntelliJ IDEA as the tool for technical writing.
 Each page gives a brief overview to get started and links to other pages in this guide for additional information.
 
 [.shadow]#image:technical-writing/udemy-course.jpeg[link={link-udemy-course},float="right",align="center"]#
-There is an link:{link-udemy-course}[online course at Udemy] that contains approx. 60 minutes of video content covering several chapters of this guide.
+There is an link:{link-udemy-course}[online course at Udemy] that contains approx. Sixty minutes of video content covering several chapters of this guide.
 By clicking on this affiliate link, you ensure that almost all the money you pay is forwarded to the maintainer of this plugin.
 
 If the information in the following pages is missing an aspect and leaves questions unanswered, visit the xref:./getting-help.adoc[] page to find more documentation resources and learn where to contact other users of the plugin to collaborate and to get answers to questions.

doc/users-guide/modules/ROOT/pages/technical-writing/installing-intellij.adoc

@@ -50,7 +50,7 @@ image::technical-writing/toolbox-start-ide.png[]
 [#other-ides-by-jetbrains]
 == Other IDEs by JetBrains
 
-The company JetBrains maintains a portfolio of different IDEs with different target audiences.
+The company JetBrains maintains a portfolio of different IDEs with different primary audiences.
 Some of them are free and have "`Community`" in their name, others need a paid subscription.
 Students at universities might get a free subscription, and there are trial periods to try out the paid subscriptions.
 
@@ -65,8 +65,8 @@ Students at universities might get a free subscription, and there are trial peri
 [#alternative-installation-options]
 == Alternative installation options
 
-Users can also download IntelliJ IDEA from the JetBrains as an archive https://www.jetbrains.com/idea/download[from the download page].
-This is a good option to install the IDE on a PC which doesn't have an internet connection.
+Users can also download IntelliJ IDEA from JetBrains as an archive https://www.jetbrains.com/idea/download[from the download page].
+This is a good option to install the IDE on a PC that doesn't have an internet connection.
 
 Some Linux distributions contain pre-packaged versions of the IDE, but as those sometimes lack features or components that are required by the AsciiDoc plugin's preview.
 Therefore, they are _not_ recommended.

doc/users-guide/modules/ROOT/pages/technical-writing/learning-asciidoc-syntax.adoc

@@ -14,7 +14,7 @@ See xref:./opening-the-first-project.adoc[] and xref:./editing-an-asciidoc-file.
 
 == Learning the AsciiDoc syntax with Kata
 
-A kata is an exercise which focuses on learning something new.
+A kata is an exercise that focuses on learning something new.
 
 The primary goals of this exercise are:
 
@@ -50,7 +50,7 @@ After this first exercise, pick other exercises which are relevant to your day-t
 
 Instead of practicing the AsciiDoc syntax alone, learners can team up with a second person to solve these exercises.
 
-There's also a collaborative web editor which has been designed for such a training.
+There's also a collaborative web editor that has been designed for such a training.
 See this https://www.ahus1.de/post/interactive-asciidoc-training[blog post] for details on how to run such a training event.
 
 == Further reading

doc/users-guide/modules/ROOT/pages/technical-writing/navigating-in-a-project.adoc

@@ -90,9 +90,9 @@ The user opens and hides the project view by clicking on menu:Project[] in the t
 
 image::technical-writing/intellij-project-view.png[]
 
-In the upper right corner there are different view variants. For technical writing, the style menu:Project[] should be used.
+In the upper right corner, there are different view variants. For technical writing, the style menu:Project[] should be used.
 
-In the upper right corner is a crosshair icon:
+In the upper right corner is a cross-hair icon:
 Clicking it selects the file
 that is opened in active editor in the tree view which allows locating a file in the project's hierarchy.
 

doc/users-guide/modules/ROOT/pages/technical-writing/opening-the-first-project.adoc

@@ -14,7 +14,7 @@ See xref:./installing-intellij.adoc[] and xref:./starting-intellij-first-time.ad
 == Opening a project
 
 A project is usually either a single folder on the local disk, or a remote Git repository.
-While a project can xref:features/advanced/multimodule.adoc[consist of multiple local folders], this is an advanced case which is possible but not recommended for users new to IntelliJ.
+While a project can xref:features/advanced/multimodule.adoc[consist of multiple local folders], this is an advanced case that is possible but not recommended for users new to IntelliJ.
 
 This dialog shows the startup screen when IntelliJ is started for the first time.
 
@@ -27,14 +27,14 @@ For a technical writing project, choose the menu entry menu:Empty Project[] to a
 
 Open:: Choose a folder on the local disk to open it as a project.
 Usually, this is the root folder of a previously checked-out Git repository.
-If the project contains a lot of files, it might help to open only a sub-folder with the documentation.
+If the project contains a lot of files, it might help to open only a subfolder with the documentation.
 
 Get from VCS::
 Specify a URL with the remote repository and an empty local folder where to check out the files.
 
 Once the step is complete, IntelliJ opens the project in the IDE view.
 
-Assuming the user chose to create an empty project with the name "`helloworld`", the result will look similar to the following.
+Assuming the user chose to create an empty project with the name `helloworld`, the result will look similar to the following.
 
 image::technical-writing/intellij-empty-project.png[]