From Confluence to Metalsmith - A Migration Story of Nuxeo Docs


Tue 15 November 2016 By Manon Lumeau

Did you notice the big change on our documentation site last week? If not, stop whatever you are doing and take a look right now. It’s worth it!

After several months of work, we are very happy to announce that a totally revamped and brand new Nuxeo Documentation site is live!

BEFORE

AFTER

It is not just an update of the look and feel. We changed the documentation tool itself, abandoning Confluence for a static website generated with Metalsmith. Today, we will discuss why we decided on the migration and how we improved the Metalsmith plugin ecosystem.

What is Metalsmith Static Website Generation?

The new documentation website is a set of textual content and graphical resources that goes through a set of piped transformations for generating the expected look and feel and links. Metalsmith handles that piping logic in JavaScript. It is possible to add new pipes, for instance one that will replace all {page page=’my-page’ space=’NXDOC’} by the expected link to a given page. Sources of the website are committed on GitHub.

Why We Abandoned Confluence & What We Gained With Metalsmith?

Confluence was a great tool when we started our documentation site - it was very easy to use, create, update, and maintain pages. But for several months now we have been facing some limitations and finally decided on the migration. Here’s why:

  • Better control on the global layout of the doc:
    The first urgent need was to simplify the documentation with a lighter and more reactive website in order to improve the navigation between pages even when they are not in the same space or have the same version. Confluence offered some template tuning possibilities but it was quite proprietary; it required deliveries and there was the burden of versions migration each time.

  • Better control on linking the same pages for different versions of the product:
    A major version of the Nuxeo Platform is released every year. It is possible to browse the entire documentation for a given version, but it is also helpful to browse the related content that was there for a former version from the same page. There was no easy way to do it in the old documentation site. We’ve now been able to implement it easily with automated link generation. We also have the ability to add a fallback link when there is no relevant page or when the concept has been modified.

  • SEO behaviour:
    Since we have full control on the HTML content of the pages, we can easily provide all required headers for search engine optimization, which is critical for us. This wasn’t possible earlier.

  • Better authoring experience (Native Markdown support and better control on page content with great content editors):
    Markdown can be added through an extension on Confluence but that wasn’t the case before. The Confluence wiki syntax is quite proprietary, which doesn’t appeal to our developers who are usually the ones writing the documentation. With simple markdown pages there’s no need to switch to “html source” anymore! Plus using Atom.io or Sublime to write content is way more comfortable. The new site is essentially a folder of text files, which allows us to edit it offline, perform bulk search, replace all the files at once, and more.

  • Better process management and quality checks:
    We have started implementing features to manage processes, such as review dates, page status, etc. Adding quality checks (for page syntax, broken links, etc.) is quite easy and we have added quite some checks and have more planned for the near future.

  • Github collaboration flow is awesome:
    It is really cool to be able to have a branch for each modification, pull requests, history of commits, etc.

Features Added to Bare Metalsmith Generators

By reading the Metalsmith documentation, you will quickly understand that everything in Metalsmith is handled by plugins. We therefore listed all the features that we wanted to keep from Confluence and we created plugins for each of them. For example:

  • Excerpt
  • Multi-excerpt
  • Tag
  • Historic
  • Page links
  • Left Menu
  • Page Review Warnings
  • Page links

We also created new plugins that were not handled by Confluence. For example, for versioning we can link pages even if they have been renamed between two versions. We also implemented a documentation review process.

Most of all, this documentation website in Metalsmith leaves more room for evolution of content, layout, graphic design, and contribution.

Migration of the Content

We used the Rest API of Confluence to migrate the content and then applied some transformation to convert it to markdown. We also stripped out all useless chunks (including getting short links, history summary, last author, tags, etc.).

What’s Next?

That is just the beginning of our project! We are already working on the second version of the documentation website, with improvements on navigation, graphic, design. As Nuxeo is growing fast, the documentation needs to scale to fit the constantly evolving needs.

We hope it will make your life easier to discover Nuxeo, learn about our products, read more documentation and contribute to it. Let us know your thoughts and impression about this new website.

Lastly, if you are interested in using the Metalsmith plugins that we are writing, GitHub is your friend :) Your feedback and improvements are always welcome! There’s a lot more coming, so stay tuned for more updates!


Tagged: Documentation, Nuxeo Platform