Publish Documentation for Your Plugin – With Writerside

Sasha Maximova

The more we work on a tool, the more intuitive and easy to use it seems. This is why documentation is sometimes postponed to the last minute, or even scrapped completely. Customers are left to figure out for themselves what the tool can do.

However, documentation benefits even a small team, especially at an early stage of a product’s development.

• Documentation helps to flatten the learning curve. Fewer users will drop off because they fail to find a feature. 
• It takes the burden off support, which is a big advantage for a small team.
• Online documentation improves content marketing and SEO. 

• Documentation is a sign of consideration and appreciation of the user. It also indicates a sense of reliability that helps build trust in the product.
  

Plugin developers can publish documentation directly to the JetBrains Marketplace. That documentation is not limited to a single page with regular text – you can also publish structured guides, complete with navigation and search.

Check out these examples:

• Grazie Professional Documentation
• Docs for JetBrains Academy   
• Rust Documentation 

How do you create such documentation for your plugin?

First of all, it’s important to define the minimum scope of your documentation.

Your users probably don’t need a full reference or UI guide, especially if you follow the IntelliJ Platform UX and UI guidelines.

They need to understand basic scenarios and how exactly your plugin makes their lives better.

What your users need is a jump-start:

• Overview or introduction: Briefly cover the plugin’s core features and benefits.
• Quick start: Step-by-step instructions on how to install and configure the plugin, its dependencies, or its prerequisites. Describe a simple scenario that demonstrates how to use the plugin. 
• Known issues or troubleshooting: Include a detailed list of all known issues and their solutions, best practices, and workarounds. Don’t forget to tell users how to collect debug information if something goes wrong.
  

Now, how do you start writing? And how will you publish what you’ve written?

Well, we have a tool for that.

JetBrains is working on its own solution for writing documentation – Writerside. You can use its Early Access Program version to write and publish documentation for your plugin, right inside your favorite JetBrains IDE.

Would you like to try it out?

1) Download the Writerside plugin on JetBrains Marketplace.

2) Create a documentation project or module in your dev project.

3) Select a template for one of the 4 main documentation types: How-to, Reference, Overview, or Tutorial. We provide the structure, and you fill it in with content.

4) Write in Markdown, inject XML elements, such as tabs, complex tables, collapsible elements, and more.

5) Publish on JetBrains Marketplace with the help of the Writerside team. The publishing process itself is not automated yet, so you’ll currently need to build your docs locally and send us the .zip archive. Here are detailed instructions on how to do that. We’ll take care of the CI/CD configurations and actual publishing.

6) Join our Slack channel for support, news, and updates. Although we assume you’ve read and agreed to it before joining, please don’t forget to review our Code of Conduct. 

See you on the writer’s side! 🤓

Subscribe to JetBrains Platform updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!