Writing user documentation

User documentation is essential to make the plugin approachable for all types of users.

Write for your readers

This guideline enables contributors to write in a style that is comprehensible for the reader.

Picturing the Reader

Don’t assume people are developers and have worked with IntelliJ before — this should be for writers or business analysts as well, and also for first-time IntelliJ users.

Naming the actor, using the active voice and the present tense makes it easier for non-native speakers to understand this document. Adding the shortcuts should help users new to IntelliJ.

Check lists for writing content

Name the actor

Examples: user, preview, editor, plugin

Provide Keyboard shortcuts for different operating systems

Example:

  • [.windows]#kbd:[Alt+F7]#

  • [.linux]#kbd:[Alt+Shift+7]#

  • [.macos]#kbd:[⌥ F7]#

displays as

  • Alt+F7 (Windows)

  • Alt+Shift+7 (Linux)

  • ⌥ F7 (macOS)

The UI theme displays an operating switcher which tries to auto-detect the operating system of the visitor, which will then show only the shortcuts relevant to the selected operating system. Therefore, always put all three operating systems into the docs.

As per the Apple guidelines, there is no + but a space between the keys.

Use active voice

Active voice: “The preview displays the result”
Passive voice: “The result is displayed”

Use present tense

Present tense: “The preview displays the result”
Future tense: “The preview will display the result”

Use only one capital letter for Keyboard shortcuts

Consistent: Alt+7
Inconsistent: ALT+7

Conventions in the source code

These conventions help writers find their way when they browse the documentation’s source code and lets them focus on the content. Writers can use the reformat functionality of the plugin using the shortcut Ctrl+Alt+L to apply these conventions.

Each sentence should be on its own line in the AsciiDoc source

This is the recommended best practice as it prevents re-flows due to reformatting and enables writers to move sentences and re-arrange paragraphs with less effort. This practice works best when writers enable word-wrap in their editor. Read more about this and other recommended practices on the Asciidoctor homepage.

Keep blank lines after section headings

This makes it easier for writers to navigate through the code of the page.

Location of content

The user documentation is published on the plugin’s website at https://intellij-asciidoc-plugin.ahus1.de/

The sources of the documentation reside in the Git repository https://github.com/asciidoctor/asciidoctor-intellij-plugin in the folder doc/user-guide.