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.

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

Check lists for writing content

Name the actor

Examples: user, preview, editor, plugin

Provide Keyboard shortcuts

Example: kbd:[Alt+7] displays as Alt+7

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

Location of content

All 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.