Provide a guide to technical writers that are new to IntelliJ

[ahus1]

Description

So far the docs assumed that the user was more or less familiar with IntelliJ. Still there are people you want to try out IntelliJ just to try out how working with AsciiDoc feels like in IntelliJ.

To cater for that, there will be an opinionated step-by-step guide starting with installing IntelliJ and pointing out all the steps on the way relevant for technical writing an the AsciiDoc plugin.

KUDOs to my friends and colleagues at Red Hat who invited me to some technical writer meetings where they showed how different IDEs work with AsciiDoc for those who will need to switch from Atom that sunsets in Dec 2022 to a new IDE.

[ahus1]

There is a now a first iteration of docs available here: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/index.html

Upcoming chapters:

• Preparing a Git repository for AsciiDoc and IntelliJ to work with a team of technical writers
• Enhance a writer's productivity with plugins for IntelliJ

[ahus1]

As suggested by @KLynn2019 in the Asciidoctor Zulip chat - it would be great to have also a chapter on Antora.

[ahus1]

To more chapters added:

• Navigating in an IntelliJ Project
• Searching in an IntelliJ Project

[infotexture]

🙏 Thanks for this initiative, it's a great idea that will be very useful to many new starters.

Preparing a Git repository for AsciiDoc and IntelliJ to work with a team of technical writers

This would be a big help, as we've struggled at times to find a common structure that works well for generating PDF via Asciidoctor, HTML with Antora, and authoring with the IntelliJ plugin. Each tool makes its own assumptions about where things like attributes should be stored, and it can be tricky to single source things if you're using all three.

It's great that your IntelliJ plugin does its best to work with the other two, so your take on best practices will be very useful.

[infotexture]

Just noticed that the keyboard shortcuts listed in the new chapters seem to be Windows-specific.

I know it's awkward to mention both options every time you refer to a shortcut (and the Mac shortcuts are included in keymap.html#macos which is linked from both topics), but might be good to mention that the Mac shortcuts are different.

[ahus1]

@infotexture - you're right, they are Windows specific. Most of them are the same on Linux, but probably not all of them.

I'd welcome a PR to add the macOS shortcuts which would show them in the text side by side.

I'm thinking about something like:

[.windows.linux]#kbd:[Alt+Enter]#/[.macos]#kbd:[⌘+Enter]#

Eventually I could then add some JavaScript to allow switching of the keyboard shortcuts, or someone else volunteers for that.

[ahus1]

@infotexture - I used my small JavaScript, HTML and CSS skills to enhance the UI to switch keyboard shortcuts based on the operating system of the visitor.

See https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/keymap.html for an example.

For anyone who wants to add macOS specific keyboard mappings. see 931b85b on how to do this.

[dfitzmau]

To more chapters added:

• Navigating in an IntelliJ Project
• Searching in an IntelliJ Project

Hello @ahus1 . Thanks for creating this document! Really needed.

Not sure if the guide could squeeze in a merge conflict section (alt+0). See: https://www.jetbrains.com/help/idea/comparing-file-versions.html

Merge conflicts can be one of the more difficult tasks that writers might face when using AsciiDoc to structure their content.

[infotexture]

I used my small JavaScript, HTML and CSS skills to enhance the UI to switch keyboard shortcuts based on the operating system of the visitor.

@ahus1 👍 That's a nice enhancement, makes sense to use that same approach in the other topics that mention shortcuts.

[ahus1]

@infotexture - sure, as time permits from me or other volunteers. One of the other pages has been converted already.

[ahus1]

Hi @dfitzmau - I added some links in 6c416ef. I rather linked to the JetBrains docs instead of duplicating the content here. The docs are open source as well - feel free to create a pull request to make small changes.

For bigger changes, please create an issue first to discuss the change, this avoids rework/wasted time if the change would go in a direction that wouldn't fit the docs.

[dfitzmau]

Hi @dfitzmau - I added some links in 6c416ef. I rather linked to the JetBrains docs instead of duplicating the content here. The docs are open source as well - feel free to create a pull request to make small changes.

For bigger changes, please create an issue first to discuss the change, this avoids rework/wasted time if the change would go in a direction that wouldn't fit the docs.

Thanks, @ahus1 , for the reply. Yes, good point. Best to avoid duplication.

I might need to consider creating an issue, because I really had to search a few sections of the open-source document on how to resolve a merge conflict in a few simple steps.

[ahus1]

New chapter available:

• Preparing a Git repository for AsciiDoc and IntelliJ to work with a team of technical writers.

[infotexture]

Great summary in that latest topic. Many of the tips there were familiar, but I also learned a few new tricks. 👏 🙇

[ahus1]

Next chapter:

• Getting help from docs and other users

Did I miss an important link or section?

[ahus1]

Added the section recommended plugins.

Still pending:

• How to resolve merge conflicts
• Antora and IntelliJ

[ahus1]

@dfitzmau - I found that there's a video in the JetBrains docs on how to resolve a merge conflict. The text now reads as follows:

Resolving merge conflicts

There’s a chapter how to resolve merge conflicts with Git in the IntelliJ docs called Resolve conflicts in Distributed Version Control Systems.

When a merge conflict occurs, it is usually good to start with Apply non-conclicting changes first, either with the All option or the magic wand icon.

For a walk-though of handling a conflict with Git, watch the 5:34 min video at the end of the IntelliJ manual page resolving conflicts.

[ahus1]

@KLynn2019 - there's now a chapter on Antora as well. It starts off with some links on where to learn about the concepts of Antora, and links to the original Antora quickstart.

It then describes some opinionated best practices how to use Antora with IntelliJ. It turned out to be longer than expected, still I hope it is useful. https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/using-antora-with-intellij.html

I might revise it later based on feedback - please comment here or in new issues, or create a PR straight away.

[ahus1]

@dfitzmau - forgot to push the changes yesterday, now they are live: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/git-integration.html#resolving-merge-conflicts

[dfitzmau]

Thanks, Alexander. Your addition will help so many writers with this complex operation. Thank you!

…

On Tue, 6 Dec 2022 at 21:44, Alexander Schwartz ***@***.***> wrote: @dfitzmau <https://github.com/dfitzmau> - forgot to push the changes yesterday, now they are live: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/git-integration.html#resolving-merge-conflicts — Reply to this email directly, view it on GitHub <#1214 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AN2E6HHNWEIOKBZ3LFUYKMDWL6XUDANCNFSM6AAAAAAR62I6VI> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

-- Darragh Fitzmaurice Technical Writer 2 Red Hat EMEA <https://www.redhat.com/> Communications House Cork Road, Waterford, X91 NY33, Ireland ***@***.*** <https://www.redhat.com/>

[dfitzmau]

@dfitzmau - forgot to push the changes yesterday, now they are live: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/git-integration.html#resolving-merge-conflicts

Thanks, @ahus1 . Would you be OK to change?

non-conlicting changes > non-conflicting changes

[ahus1]

@dfitzmau - I've change the word, this should now be correct. If you find other typos or corrections, please note them here, or open a pull request for the docs (preferred). Each page has an "Edit" link in the top right corner to edit it in the browser. Also the Git repository can be cloned to prepare a pull request.

[infotexture]

@ahus1 The new topic on Antora setup is very helpful and fills a few gaps on how to set things up so that all the tools work well together. The details on folder structures and repo layouts are particularly useful and include a few good tips I haven't seen elsewhere.

One thing that's not yet entirely clear to me is the rationale for a separate playbook repository. It makes sense if the content itself is distributed across multiple content repos, but in simpler setups where all the content/components/modules live in a single repo, why not store the playbook there too?

(I trust there's a good reason for this if it's generally recognized as best practice, but haven't heard that explanation yet.)

🙏 Thank you for your service to the community. This is another great resource. 🙇

[ahus1]

@infotexture - that's a great question. And you are right: the simpler the setup is, the more likely it is that you'll put the playbook and the UI into one repository with the content.

The moment one actively maintains multiple versions of the content in different branches, it is IMHO the moment where a separate playbook repository make sense. Dan mentioned in another thread somewhere a scenario that if you have a single content repository with multiple versions of the content, the playbook (and the UI) might be another branch.

I'll elaborate more on this in the next few days and update the docs.

[ahus1]

@infotexture - while the longer text is on the way, here's a small sneak preview from commit 54844bf

The tradeoff: Users might struggle with this approach [of checking out mulitple repositories], and would want to open only a single repository as they usually do. Such a scenario might be where the Antora content is stored side-by-side with source code or other information stored in the repository. If there are only few cross-references between the components, checking out other content repositories is seen as an unnecessary overhead, and checking out the playbook repository is a nuisance.

In such a situation, it might be simpler to duplicate the playbook’s attributes in an .asciidoctorconfig file, and authors would rely on the IDE’s preview to prepare their changes.

When only a single content repository is checked out, links to other components will not show the page title, can’t be validated in the IDE and can’t be navigated to. This might change in a future version of the AsciiDoc plugin for IntelliJ once Antora Atlas is supported: With the information stored in the site manifest, the local IDE can retrieve the page titles of the pages in other components together with their links to the final site. Follow GitHub issue #1250 for the progress on this issue.

[ahus1]

There's now a new area which over time might cover additional Antora questions:

https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/antora/index.html

The first question it tries to answer "How many repositories to use for components and playbooks"

This content might need additional copy-editing. Feel free to lend a hand for structure and typos.

[ahus1]

There are now docs how to handle tables: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/technical-writing/using-tables-in-a-project.html

[ahus1]

There is now a page describing how generated contents can be handled in Antora

https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/antora/generated-content-in-antora.html