Cassandra Targett created SOLR-14173:
----------------------------------------
Summary: Ref Guide Redesign
Key: SOLR-14173
URL: https://issues.apache.org/jira/browse/SOLR-14173
Project: Solr
Issue Type: Improvement
Security Level: Public (Default Security Level. Issues are Public)
Components: documentation
Reporter: Cassandra Targett
Assignee: Cassandra Targett
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 (issue TBD) 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-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
