[jira] [Updated] (SOLR-14173) Ref Guide Redesign Phase 1: Page Design

["Cassandra Targett (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/SOLR-14173?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Cassandra Targett updated SOLR-14173:
-------------------------------------
    Fix Version/s: 8.6

> Ref Guide Redesign Phase 1: Page Design
> ---------------------------------------
>
>                 Key: SOLR-14173
>                 URL: https://issues.apache.org/jira/browse/SOLR-14173
>             Project: Solr
>          Issue Type: Improvement
>          Components: documentation
>            Reporter: Cassandra Targett
>            Assignee: Cassandra Targett
>            Priority: Major
>             Fix For: 8.6
>
>         Attachments: SOLR-14173.patch, SOLR-14173.patch, blue-left-nav.png, gray-left-nav.png
>
>
> 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.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org