Design and build a collaborative user experience for a chance to win cool prizes!
Blog

Vaadin Docs – a step further to online documentation

By  
Jens Jansson
Jens Jansson
·
On Jan 14, 2016 6:45:00 AM
·

A few years ago Vaadin was a company with only one big product, namely Vaadin Framework. The documentation for Vaadin Framework has been presented in the form of Book of Vaadin, which we are very proud of and to be honest, the name has always been a nice addition, as well. Over the years, however, our product portfolio has grown a lot. Some of the new products’ documentation was added to the book, making it bigger. Others had the documentation placed outside Book of Vaadin because it made more sense that way. We ended up with a documentation that was kind of like Star Wars: the earlier parts were stylistically very far apart from the later parts. One saga alone could not cover everything from Anakin Charts to Darth Vaadin in a way that you still understood where it came from and what it was about. So we did something about it and built the ultimate solution: Vaadin Docs.

Vaadin Docs is the place for finding documentation on anything related to Vaadin and it is structured with the products on top level. If you’re looking for HTML Elements, you’ll find them easily and if you’re looking for Spreadsheets, you’ll find them with a click. The documentation site’s main focus was to ease the navigation and browsing of topics. We achieved this by having a well structured and collapsible menu that follows along as you scroll and shows where you are. The site is designed to work as well on mobile as on desktop and includes search functionalities so that you can easily find the topic that you are looking for. Additionally, the documentation has been moved online to each product’s repository and there is a nifty ‘edit on GitHub’ button on each article where you can easily suggest corrections to the documentation. On the technical side, the documentation itself was converted from DocBook to AsciiDoc format to make it more easily readable, understandable and editable to anyone who wishes to contribute.

Book of Vaadin is still available as PDF, ePub and printed formats and we’ll continue printing it and using it. It is still the main documentation for Vaadin Framework; just not for all products. Without the need to encompass other products’ documentation in the book, we can now also renew the content of the book to give the best learning experience of Vaadin Framework in a leaner way, as its purpose has always been.

I hope you enjoy the new Vaadin Docs site as much as I do. Check it out and share what you think of it with us.

See the Vaadin Documentation
Jens Jansson
Jens Jansson
Product Manager at Vaadin. Vaadin developer and expert. Gamer and coder. https://www.linkedin.com/in/jjansson/ - https://twitter.com/Peppe_ - https://github.com/Peppe
Other posts by Jens Jansson