JetBrains has released a public preview of Writerside, a new documentation editor based on the company’s internal tooling. Writerside works either as a standalone IDE or as a plugin for other JetBrains IDEs, and projects build to become documentation websites.

Writerside documentation is written in either Markdown or semantic markup (XML). JetBrains nudges users towards the semantic option, especially for larger projects, since it has more features and encourages consistency. Semantic markup borrows many elements from HTML, including familiar tags such as <p>, <a>, <img>, <table> and many more. Some things are different though: a list is <list> and not <ul> or <ol>. Pressing < in the editor brings up a list of all the valid elements for the particular context, and pressing F1 shows a help panel for the selected element, a feature which is most useful for learning the markup.

A Writerside project is composed of topics and help instances. Each help instance has a table of contents. In the simplest case there will be one help instance in the project, but it is possible to have multiple instances enabling topics to be shared between them, while customizing each instance for a particular context. There is also support for multiple versions, so that authors can maintain documentation for different versions of a product, controlled via git branches.

As you would expect from JetBrains, Writerside has rich support for smart actions such as converting a block of content to a different format, and an array of templates for frequently used elements like tabs, tables and lists. Support for common patterns such as step by step explanations are built in, in this case with <procedure> and <step> tags. There is also a <tldr> (too long, didn’t read) tag for quick summaries of information, limited to one per page. Adding code snippets is easily done with a <code-block> tag. There is also a tag that will generate an API reference from an OpenAPI (Swagger) specification file.

The way Writerside works will be familiar to developers. Projects are coded, built and deployed, and a project with broken markup will not build. Projects build to HTML projects that can be deployed as static websites, or published as GitHub Pages, GitLab, or TeamCity Cloud. Search can be provided via Algolia though a paid account will be needed for use at scale.

Writerside addresses an important niche, particularly as recent research identifies high quality documentation as a key factor in team performance, reducing burnout and increasing productivity.

That said, for software documentation, Writerside projects are vulnerable to getting out of step with the code, as opposed to approaches like Javadoc, JSDoc or Doxygen where documentation is generated from comments in the code itself, which is easier for developers to keep up to date.

This is an early access preview, but we also found the documentation for Writerside itself could do with more information on advanced topics. For example, the explanation of semantic markup makes a point of saying that a semantic tag can have the way it is rendered changed globally, but there is no explanation of how to do this, or how to extend the semantic markup with additional tags. “With Writerside you get a modern web help with a fixed layout, adapted for mobile devices,” the documentation states. There is a section on how to customize the look of the generated site but this is limited to colors and logos.