Writing user documentation
User documentation is essential to make the plugin approachable for all types of users.
This guideline enables contributors to write in a style that is comprehensible for 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.
- Name the actor
Examples: user, preview, editor, plugin
- Provide Keyboard shortcuts
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
All user documentation is published on the plugin’s web site 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.