[
https://issues.apache.org/jira/browse/SOLR-14173?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Cassandra Targett updated SOLR-14173:
-------------------------------------
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.
was:
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.
> 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
> 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-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
