[SOLR-14173] Ref Guide Redesign Phase 1: Page Design

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 8.6
• Component/s: documentation
• Assignee: Cassandra Targett
• Reporter: Cassandra Targett
• Created: 07/Jan/20 17:42
• Updated: 15/Jul/20 18:11
• Resolved: 05/May/20 23:43

Description

The current design of the Ref Guide was essentially copied from a Jekyll-based documentation theme (https://idratherbewriting.com/documentation-theme-jekyll/), which had a couple important benefits for that time:

• It was well-documented and since I had little experience with Jekyll and its Liquid templates and since I was the one doing it, I wanted to make it as easy on myself as possible
• It was designed for documentation specifically so took care of all the things like inter-page navigation, etc.
• It helped us get from Confluence to our current system quickly

It had some drawbacks, though:

• It wasted a lot of space on the page
• The theme was built for Markdown files, so did not take advantage of the features of the jekyll-asciidoc plugin we use (the in-page TOC being one big example - the plugin could create it at build time, but the theme included JS to do it as the page loads, so we use the JS)
• It had a lot of JS and overlapping CSS files. While it used Bootstrap it used a customized CSS on top of it for theming that made modifications complex (it was hard to figure out how exactly a change would behave)
• With all the stuff I'd changed in my bumbling way just to get things to work back then, I broke a lot of the stuff Bootstrap is supposed to give us in terms of responsiveness and making the Guide usable even on smaller screen sizes.

After upgrading the Asciidoctor components in SOLR-12786 and stopping the PDF (SOLR-13782), I wanted to try to set us up for a more flexible system. We need it for things like Joel's work on the visual guide for streaming expressions (SOLR-13105), and in order to implement other ideas we might have on how to present information in the future.

I view this issue as a phase 1 of an overall redesign that I've already started in a local branch. I'll explain in a comment the changes I've already made, and will use this issue to create and push a branch where we can discuss in more detail.

Phase 1 here will be under-the-hood CSS/JS changes + overall page layout changes.

Phase 2 (SOLR-14444) will be a wholesale re-organization of all the pages of the Guide.

Phase 3 (issue TBD) will explore moving us from Jekyll to another static site generator that is better suited for our content format, file types, and build conventions.

Issue Links

• is depended upon by: SOLR-14444 Ref Guide Redesign Phase 2: Page Organization Overhaul