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

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

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 a recommended best practice as it prevents reflows 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 this and other best practices on the Asciidoctor homepage.

Keep blank lines after section headings

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

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.