Try the new documentation site

Comprehensive technical documentation goes hand-in-hand with open-source software. Vaadin has grown significantly since its original release. With recent additions, such as Fusion, Collaboration Engine, and Design System, the documentation for the product and its features required a scalable foundation that’s easy to maintain going forward.

After a beta-testing phase, we’ve finally launched the new vaadin.com/docs site. It’s now easier to navigate, contribute to, get started with, and overall a big improvement for the experience.

Check out the new docs site.

All documentation is in one place

All documentation is now sourced from one repository, which makes it easier to keep the content coherent and the style consistent. We utilize Vale to automate the style guideline checks, which is very helpful as we have a big group of people writing content.

With one repository, it is also easier to manage contributions from our community. Fixing small issues, like spelling errors and bugs in code examples, are more than welcome as pull requests. For anything bigger, it’s better to start off with an issue, and ask for guidance before investing time in writing larger pieces of content.

Component documentation is moving

One of the biggest changes for documentation readers is that we are moving the documentation for our component library (also known as Design System) from vaadin.com/components to the documentation site along with all other product documentation.

Now that the component documentation is no longer tied to the individual component repositories, and to Vaadin releases, we can update it much faster. The previous setup was rigid, and required a full Vaadin release and a full vaadin.com redeployment. The new setup enables us to iterate content much faster, roughly 20–30 mins from commit to production.

The component documentation work is still in progress and currently only available in the latest documentation. The previous component documentation will be available until we have migrated all content to the new location.

Documentation versions

Another big change is how we manage documentation versions:

All long-term support releases (LTS) continue to have dedicated documentation versions. However, we no longer have separate documentation versions for non-LTS major versions (Vaadin 14 and above). The “latest” documentation covers all currently maintained major versions. At the time of writing, that means Vaadin 18 and 19.

In addition, pre-releases do not get separate documentation versions. Instead, documentation for features that are in a pre-release version are bundled together with the stable feature documentation. This change makes it easier to discover upcoming features. For example, the documentation for features in Vaadin 14.6 starts showing in the Vaadin 14 documentation once we have them available in 14.6.0.alpha. The same principle applies for new features coming in Vaadin 20. These upcoming features are clearly marked with a “since” badge, so you know if you need to update the Vaadin version you are using in your project to get them.

Code example improvements

The documentation repository is actually a regular Vaadin application project, with a pom.xml file and src and frontend folders.

The code examples are pulled from these source files – for both Flow (Java) and Fusion (TypeScript) users – allowing you to expand the snippets to view the full source, removing guesswork about the required imports and other details such as additional source files used in the example.

The example code snippets are also ensured to compile with the Vaadin version we are using in the documentation (which can be a pre-release version as well). Note that this doesn’t apply to all code examples yet – it’s a long process to update all of them to use this mechanism. Let us know if some of the code examples aren’t working for you!

Those code examples can also choose to render a live UI example above the source code. This is obviously most useful for the component documentation, but allows us to illustrate and demonstrate other features in action as well.

All code examples now also get a “copy to clipboard” button, making it easier for you to pick up snippets into your project. This small improvement was long overdue!

Content structure updates

The content structure (information architecture) has also been updated, and is not exactly the same between documentation versions.

In the latest documentation, Fusion is now its own top-level section, instead of being part of Flow. Theme documentation has moved under Design System, and Designer, TestBench, and Multiplatform Runtime can be found under a joint Tools section.

Topics that span across more than one facet of Vaadin are found under the Get Started section, which helps new users get up and running with Vaadin development. It also helps you get your application deployed and includes Vaadin version upgrades.

As a completely new addition, we now have a unified place for instructions on how to contribute to all Vaadin projects, with editor setting and testing setup instructions.

Smaller improvements

Along the bigger changes, we also took time to improve the browsing and reading experience. The new docs site has:

• faster navigation
• improved search, with a handy keyboard shortcut Ctrl/Cmd+K
• Improved readability
• a "table of contents” for each article, making it easier to quickly get a sense of the contents
• a “last updated” date at the bottom of each page, which links to the change log of that article
• keyboard and screen reader accessibility.
  
  

Under the hood

We retired our previous Jekyll based site mainly due to its lack of support for rendering integrated examples. We opted for Gatsby instead thanks to its de facto status in static technical documentation sites. Its support for webpack allows us to bundle our rendered examples without much effort, and the large ecosystem around it means we didn’t have to build everything ourselves. Furthermore, our team is far more comfortable developing with JavaScript and TypeScript than with Ruby.

The previous docs site was embedded within the main vaadin.com website, which rendered the HTML output produced by Jekyll. We wanted to decouple the documentation site deployment from the marketing website, while still keeping the main navigation and visual style consistent across both. We achieved this by implementing the new design system and a reusable header component that allows us to split the website into sections while still maintaining the same look and feel.

The discussion feature remains disabled. However, you can join our Discord server to discuss all things Vaadin.

Design System Publisher

While this update is largely driven by our internal needs to make maintenance easier, and to make the experience great for our users, we had one external reason to rebuild the documentation system. We are launching a new commercial tool, Design System Publisher, which makes it super easy for you to set up our own customized design system documentation site. It’s not just a static site generator that you will be getting, but full design system documentation with design guidelines for all Vaadin components.

The product owner for Vaadin Design System, Rolf Smeds, gave a small glimpse into this new product in a recent live-stream on Twitch.

We are currently looking for pilot customers to test Design System Publisher. Contact our sales team, if you are interested.

What's next?

The site remains a work in progress that we will continuously update along with our products. However, there is still work to be done in the current version, including expanding topics, such as security, and adding important sections like internationalization (i18n). We also plan to integrate the API docs (both Java and TypeScript), including component styling docs, which are currently hosted separately from the main documentation.

We’re actively looking for feedback and suggestions. Please, don’t hesitate to send us issues or open pull requests on GitHub! You can also comment your wishes below.