First iteration of docs with a step-by-step guide to install IntelliJ

(#1214)

doc/users-guide/modules/ROOT/nav.adoc

@@ -1,5 +1,11 @@
 * xref:index.adoc[]
 * xref:quick-start.adoc[]
+* xref:technical-writing/index.adoc[]
+** xref:technical-writing/installing-intellij.adoc[]
+** xref:technical-writing/starting-intellij-first-time.adoc[]
+** xref:technical-writing/opening-the-first-project.adoc[]
+** xref:technical-writing/editor-the-file-asciidoc-file.adoc[]
+** xref:technical-writing/git-integration.adoc[]
 * xref:installation.adoc[]
 * xref:recommended-settings.adoc[]
 * xref:features.adoc[]

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

@@ -41,10 +41,12 @@ It provides the writer with...
 
 == Where to go from here
 
-To continue your journey,
+To continue the journey with one of the following:
 
-* visit the (short) xref:quick-start.adoc[] guide or (in depth) xref:installation.adoc[] guide,
-* read about the xref:features.adoc[], or
-* use the navigation on the left to learn about a specific topic you are interested in.
+* Visit the
+** (short) xref:quick-start.adoc[] guide or the
+** (in depth) xref:technical-writing/index.adoc[] guide.
+* Read about the xref:features.adoc[].
+* Use the navigation on the left to learn about a specific topic you are interested in.
 
 If you got questions, please raise them as a https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues[new GitHub issue].

doc/users-guide/modules/ROOT/pages/installation.adoc

@@ -6,6 +6,11 @@ ifndef::env-site[]
 :imagesdir: ../images
 endif::[]
 
+{description}
+
+For users already familiar with JetBrains IntelliJ, there's a xref:quick-start.adoc[] documentation.
+For those new to IntelliJ, there is a xref:technical-writing/index.adoc[] with a step-by-step-guide installing IntelliJ for technical writing.
+
 [#prerequisites]
 == Prerequisites
 

doc/users-guide/modules/ROOT/pages/quick-start.adoc

@@ -7,7 +7,8 @@ ifndef::env-site[]
 endif::[]
 
 {description}
-Continue to section xref:installation.adoc[] for a more detailed guide.
+Change to the page xref:installation.adoc[] for a more detailed guide,
+or xref:technical-writing/index.adoc[] for a step-by-step-guide installing IntelliJ for technical writing.
 
 == Prerequisite
 

doc/users-guide/modules/ROOT/pages/recommended-settings.adoc

@@ -11,23 +11,16 @@ endif::[]
 [#configuring-editor]
 == Configuring editor
 
-. An AsciiDoc recommended practice is to have link:https://asciidoctor.org/docs/asciidoc-recommended-practices/[_one sentence per line_].
-This can lead to lines larger than the editor's width.
-+
-Using soft wraps will make the content readable in the editor, as each line wraps at the width of the editor.
-+
-Go to menu:File[Settings... > Editor > General > Soft Wraps] and enable soft wrap for the file extension you use for AsciiDoc files (usually *.adoc).
-+
-image::enable-softwrap.png[Editor settings showing soft wrap]
+include::partial$enable-soft-wrap.adoc[]
 
 == Configuring preview
 
-. To get the best preview experience, switch the preview browser to _JavaFX WebView_ or _JCEF Browser_.
+To get the best preview experience, switch the preview browser to _JavaFX WebView_ or _JCEF Browser_.
 See below how to <<enable-javafx-jcef-for-android-studio,enable JavaFX or JCEF for Android Studio>>.
-+
+
 Go to menu menu:File[Settings... > Languages & Frameworks > AsciiDoc] to review or change this setting.
 If neither JavaFX of JCEF preview is not available, refer to xref:installation.adoc#prerequisites[Installation Prerequisites].
-+
+
 image::settings-asciidoc.png[AsciiDoc settings]
 
 If your preview is blurry, xref:faq/blurry-preview.adoc[follow these instructions to remedy this].

doc/users-guide/modules/ROOT/pages/technical-writing/editor-the-file-asciidoc-file.adoc

@@ -0,0 +1,111 @@
+= Editing an AsciiDoc file in IntelliJ
+:navtitle: Editing an AsciiDoc file
+:description: Adding a file to a project and editing AsciiDoc content in an existing project.
+
+{description}
+
+include::partial$technical-writing-series.adoc[]
+
+== Prerequisites
+
+This assumes that IntelliJ IDEA is open with an either empty project or a project with some existing content.
+See xref:./opening-the-first-project.adoc[] on how to do this.
+
+== Adding an AsciiDoc file
+
+This creates a new file in an existing project that can later be edited.
+
+To add a file:
+
+. Right-click on a folder in the project view where the new file should appear.
++
+Assuming the user wants to create a file in the root folder empty project "`helloworld`", they would click on the bold text "`helloworld`" (see <<intellij-first-file,screenshot>> below).
+
+. Choose from the context menu the item menu:New[AsciiDoc File].
++
+If the menu item for the AsciiDoc file is missing in the steps below, the AsciiDoc plugin wasn't installed in the prerequisite step.
+Rectify this by following the steps in xref:installation.adoc#marketplace-via-settings[Installation via JetBrains Marketplace via the IDE's settings], then return here to continue.
+
+. Enter the new file name, and choose either an empty template or the Article template.
+
+. Press btn:[OK]
+
+When choosing the article template, and using a file name `README.adoc`, the result should look similar to the following screenshot.
+
+[[intellij-first-file]]
+image::technical-writing/intellij-first-file.png[]
+
+== Configuring the Editor
+
+include::partial$enable-soft-wrap.adoc[]
+
+== IDE menus and tool windows
+
+This section describes the most important tool at the borders of the IDE's window as shown below.
+
+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.
+
+. The structure view displays the structure of the current AsciiDoc file in the editor.
+Clicking on "`Structure`" hides and shows this view.
+
+. In the editor window, the user can update the text as needed.
+
+. A toolbar at the top allows formatting of content and toggles the preview.
+Hover with the mouse over the different icons until a description appears.
+
+. The preview shows the content from the editor.
+
+== Editor
+
+In the editor, the user can update the content.
+It has syntax highlighting to improve legibility.
+On the left of the editor window, small icon:minus[] icons allow the user to collapse sections and icon:plus[] icons to expand sections.
+Line numbers help with the orientation.
+
+When the IDE suspects a problem, for example, a missing image or a broken reference, it underlines the text with a red line.
+It uses similar highlighting for suspected spelling and grammar errors.
+
+The main things to know about the editor are:
+
+* When the user types the three letters kbd:[a]kbd:[d]kbd:[-], the editor suggests live templates for common AsciiDoc structures like lists, links and source code.
+Continue typing to narrow down the list, use the up and down arrows to highlight an entry, and use kbd:[Enter] to select an entry.
+
+* When typing a file name as part of an image macro or a reference, kbd:[Ctrl+Space] shows a list of suggestions.
+Press kbd:[Tab] to replace the text in editor for the current reference or press kbd:[Enter] to insert the text in the editor.
+
+* Using kbd:[Alt+Enter], the user can trigger context-specific features of the IDE, especially when there is an underlined text that indicate warnings and errors.
+Those features range from creating a missing file to choose a correct word when there is a spelling or grammar mistake.
+
+* After placing the cursor on an include-macro or a reference and pressing kbd:[Ctrl+B], the IDE opens that file in a new editor tab.
+
+* To rename an attribute name, file name or reference, place the cursor on it and press kbd:[Shift+F6], and the IDE renames the reference in all places if the checkboxes are enabled in the dialog that pops up after the key was pressed.
+
+* To format the complete file or a selection of text, press kbd:[Ctrl+Alt+L].
+The default configuration removes unnecessary blanks and applies the one-sentence-per line rule. See xref:features/advanced/reformatting.adoc[] for details.
+
+To learn more about the editor's features, read the page xref:features/editor.adoc[].
+
+To learn about the shortcuts in the IDE and the editor, read the page xref:features/keymap.adoc[].
+
+== Preview
+
+Once the user places the cursor in the editor, the preview scrolls so that it shows this paragraph in the preview.
+
+The main things to know about the preview are:
+
+* Clicking on an external link opens them in a new window of the system's browser.
+
+* Clicking on an internal link opens the file in the editor.
+
+* Clicking on text content places the cursor in the editor in that paragraph.
+If the content is from an included AsciiDoc file, the editor opens that file in a new editor tab.
+
+To learn more about the preview's features, read the page xref:features/preview.adoc[].
+
+== Further reading
+
+Continue to xref:./git-integration.adoc[] for the next step of this series.

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

@@ -0,0 +1,48 @@
+= Collaborate with others using IntelliJ's Git integration
+:navtitle: Collaborate using Git
+:description: Setting up IntelliJ IDEA when starting it for the first time.
+
+{description}
+
+include::partial$technical-writing-series.adoc[]
+
+== Prerequisites
+
+This assumes that IntelliJ IDEA is already installed on the PC and is started and that the reader is familiar with editing content in IntelliJ.
+See xref:./installing-intellij.adoc[] and xref:./editor-the-file-asciidoc-file.adoc[] on how to do this.
+
+In order for the Git functionality in IntelliJ to work, the user needs to install a Git client.
+
+== Accessing Git from the IntelliJ GUI
+
+This paragraph assumes that the user wants to use IntelliJ's integrated Git functionality.
+To use the Git command line, choose the "`Terminal`" toolbox tab in IntelliJ to interact with the command line instead of following these steps.
+
+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`".
+
+=== Overview of the controls and tool windows
+
+image::technical-writing/intellij-git.png[]
+
+. Git tool window, click on "`Git`" to show and hide the window.
+
+. With the "`Log`" tab active, it shows local and (if available) remote branches, plus the commits in the repository.
+
+. In the menu:Branch[] dropdown, select _HEAD_ to show only the commits of the current branch.
+
+. The "`Commit`" tool window shows all local changes that can then be committed.
+
+=== Learning more about Git functionality
+
+See https://www.jetbrains.com/help/idea/using-git-integration.html[the IntelliJ documentation] for details.
+Use menu:Help[Learn IDE Features] and choose the next final section "`Git`" to start the tutorial covering Git.
+
+== Further reading
+
+This is the final page of the guide.
+Return to the overview xref:./index.adoc[].

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

@@ -0,0 +1,46 @@
+= Setup for technical writing
+:description: This article guides users new to IntelliJ IDEA through the necessary steps to set up their environment for technical writing with AsciiDoc.
+
+{description}
+
+It describes best practices and shows an opinionated approach to make it simple for users new to IntelliJ.
+
+For users already familiar with JetBrains IntelliJ, there's a xref:quick-start.adoc[] documentation.
+For advanced installation options, see the page xref:installation.adoc[].
+
+== Why to use IntelliJ for technical writing
+
+The AsciiDoc plugin provides an as-you-type preview, syntax highlighting,  auto-completion and content validation in one plugin.
+The IntelliJ IDE offers a great integration with Git and also plugins for spell and grammar checking.
+
+To get a full overview of all features of the plugin, see xref:features.adoc[].
+
+== Steps to set up a writer's environment
+
+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.
+
+. xref:./installing-intellij.adoc[Installing IntelliJ IDEA as the workplace for technical writing].
+. xref:./starting-intellij-first-time.adoc[Starting IntelliJ IDEA for the first time and installing the AsciiDoc plugin].
+. xref:./opening-the-first-project.adoc[Opening the first project in IntelliJ IDEA].
+. xref:./editor-the-file-asciidoc-file.adoc[Adding a file to a project and editing AsciiDoc content in an existing project.].
+. xref:./git-integration.adoc[Collaborate with others using IntelliJ IDEA's Git integration].
+
+////
+. xref:./preparing-a-git-repository.adoc[Preparing a Git repository for AsciiDoc and IntelliJ to work with a team of technical writers].
+. xref:./recommended-plugins.adoc[Enhance a writer's productivity with plugins for IntelliJ].
+////
+
+== Improving this guide
+
+Each of the pages in the guide has an "`Edit this page`" link in the upper right corner.
+Use this to edit the content on GitHub.
+As an alternative, all content to this guide is hosted in the https://github.com/asciidoctor/asciidoctor-intellij-plugin[Git repository of the AsciiDoc plugin] in the _doc_ folder, so it can be edited in an IDE like any other AsciiDoc content.
+
+If there are missing features, link:mailto:[email protected]?subject=Feedback%20to%20IntelliJ%20Technical%20Setup[contact the maintainer via email] or https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues/new/choose[create an issue on GitHub].
+
+== Further reading
+
+To get a full overview of all features of the plugin, see xref:features.adoc[].
+
+To custom the plugin's settings, see xref:recommended-settings.adoc[] for recommended settings.

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

@@ -0,0 +1,76 @@
+= Installing IntelliJ for technical writing
+:navtitle: Installing IntelliJ
+:description: Follow these steps to install IntelliJ IDEA on a PC.
+
+{description}
+
+include::partial$technical-writing-series.adoc[]
+
+== Prerequisites
+
+This guide assumes that IntelliJ is about to be installed on either Windows, macOS or Linux.
+
+* *Windows:* 64-bit Windows 8 or newer
+* *macOS:* macOS Mojave (10.14) or newer
+* *Linux:* 64-bit x86, glibc 2.17 (Ubuntu 18.04 or newer). +
+The following packages must be present: +
+`+libfuse2 libxi6 libxrender1 libxtst6 mesa-utils libfontconfig libgtk-3-bin+`
+
+The installation requires an Internet connection to download about 700 MB.
+See <<alternative-installation-options>> to install without an Internet connection.
+
+== What to install and why
+
+This guide will install JetBrains IntelliJ IDEA Community edition, which is free, doesn't need a subscription and is sufficient for technical writing with the AsciiDoc plugin.
+See <<other-ides-by-jetbrains>> below for more details.
+
+To install it, this guide uses the JetBrains Toolbox as it allows a unified approach across all operating systems and an automated update procedure.
+See <<alternative-installation-options>> below for alternatives.
+
+== Installing IntelliJ IDEA via the JetBrains Toolbox
+
+Follow these steps to install IntelliJ IDEA via the JetBrains Toolbox:
+
+. Download the Toolbox App from the https://www.jetbrains.com/toolbox-app/[Toolbox homepage].
+. On Windows and macOS: Start the installation.
+On Linux: Extract the archive and start the executable.
+. After the installation, the JetBrains Toolbox is started automatically.
+Users can start it later like any other app from the list of installed applications.
+. Choose the button btn:[Install] next to the IntelliJ IDEA Community Edition.
+This will download and install the IDE.
+The time to install depends on the speed of the internet connection to download approx. 600 MB.
++
+image::technical-writing/toolbox-install-ide.png[]
+. After the installation is complete, users can start the installed IDE like any other locally installed application or directly by clicking the IDE in the toolbox.
++
+image::technical-writing/toolbox-start-ide.png[]
+
+*Next step:* Continue on page xref:./starting-intellij-first-time.adoc[].
+
+[#other-ides-by-jetbrains]
+== Other IDEs by JetBrains
+
+The company JetBrains maintains a portfolio of different IDEs with different target 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.
+
+* The IntelliJ IDEA Community and IntelliJ IDEA Ultimate editions target Java developers.
+
+* For Python developers, there is PyCharm Community, PyCharm Edu and PyCharm Ultimate.
+
+* For web developers, there is WebStorm.
+
+* For Android developers, there's Android Studio, which unfortunately requires some additional steps to enable the preview, see xref:features/preview/jcef-preview.adoc#choose-jdk[JCEF Preview documentation about Android Studio].
+
+[#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.
+
+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.
+
+== Further reading
+
+Continue to xref:./starting-intellij-first-time.adoc[] for the next step of this series.