Many of you from our valued community will be familiar with the Nutanix Bible. For many years the Nutanix Bible has been and still is a cornerstone of our technical resources collection, providing in-depth explanations of how many Nutanix products and technologies work “under the covers”.
Original Layout
The Nutanix Bible was originally published as a single HTML page and, from a user perspective, this method was usable and provided all the information in one place. However, making back-end content updates could sometimes be a little cumbersome. This certainly doesn’t reflect negatively on our colleague and friend Steve Poitras, the original creator of the Nutanix Bible. Although Steve has since moved on from Nutanix, Steve’s vision for the Nutanix Bible as an invaluable resource was realised in more ways than one. Thanks, Steve. 🙂
New Layout and Design
The Nutanix Technical Marketing Engineering (TME) team recently started a project aimed at improving how the Nutanix Bible is managed. Our key aims were as follows.
1. Easier Navigation
From the moment the Nutanix Bible loads, the main content sections are right there in front of you. This should make getting to the section and chapter you need much easier.
2. Content Management System
For content management we settled on Jekyll.
Markdown being as popular as it is, using a system like Jekyll allows us to remove much of the “manual” HTML editing that the original design required. The original design was a single large HTML file, with the entire file requiring updates when content was altered. For context, the original Nutanix Bible was more than 12,000 lines of HTML! Although HTML isn’t at all difficult to master, one misplaced or omitted closing tag could potentially break the entire site.
3. Search All The Things
Having one long HTML page allowed search via built-in browser functionality, but didn’t allow us to control how many results were returned or how those results were formatted.
In the new Nutanix Bible, we’ve added search functionality to the side navigation menu. This full-text search operates just as you’d expect, with the results displayed as you type.
Note: As this article is being written, there is a known minor issue that shows unexpected subtitles next to some search results. This will be fixed soon and doesn’t impact overall functionality.
4. Easier and Quicker Updates
Breaking the overall content into smaller, easily-editable sections makes content updates much easier. This applies not only at user/visible level, but also at file level on the back-end. These are the individual Markdown files we supply to the Jekyll build engine.
Breaking the content into individual sections allows editing by multiple contributors without fear of impacting anyone else’s work. This sounds minor, but in a team environment this is an important consideration. On the back-end we already do a lot of this by utilising industry-standard practices such as Git pull requests and multiple levels of PR review. This improves content updates as running a diff on one chapter is significantly easier than the same process on 12,000 lines of HTML.
5. Load Time Improvements
The smaller sections also load much faster, vs the need to load the entire site at one in the previous version.
For example, the Liquid templating system allows us to generate a static table-of-contents before the site is deployed, thereby further reducing load times and client-side processing requirements as the page is rendered.
6. Other Back-end Improvements
The Liquid templating system allows some other interesting features, too. For example, conditional rendering based on almost any condition we choose, vs just “hiding” a section with an HTML comment block. On its own this sounds minor but as part of an overall team-managed system it allows much easier staging and testing, before deploying to production.
Same content, though!
Although our new design and layout are now in place (check it out here), it is important to note the Nutanix Bible content itself hasn’t changed. With the exception of a few sections that are no longer relevant to current product versions, the original Nutanix Bible content is still there in all its glory.
Discussing everything from navigating the Prism User Interface to how data blocks move around the physical storage devices and much more, the content our customers have come to love is still just as easily available as it was before.
This collaborative effort was managed by Laura Jordana (Principal Technical Marketing Engineer), Wes Kennedy (Senior Technical Marketing Engineer) and Chris Rasmussen (Developer Content Architect). Huge thanks to all involved, as well to our colleagues that took the time to provide feedback and comments along the way.
Thanks for reading and have a great day. 🙂