Page History

...

1. Extensive reorganization of nearly all pages.
2. Extensive page re-naming and content consolidation (leading to several page deletes).
3. Split the Solr Tutorial into parts.
4. Standardization of "standalone", "leader/follower", "legacy".
5. New formatting and layout styles.

New Section Organization

The primary goal in thinking through a better way to organize the content was to reduce the number of "top-level" categories to a significantly smaller list, but this wasn't just an exercise in moving sections. There are changes to the 2nd, 3rd, and 4th level categories. 

...

There are now 5 main top-level categories (screenshot below):

• Getting Started
• Deployment Guide
• Configuration Guide
• Schema and Indexing Guide
• Query Guide

...

The massive Solr Tutorial has been split into 4 pages - an intro and then one for each exercise - and there is a new dedicated section under "Getting Started" for Tutorial content. The AWS Tutorial and the "Getting Started with SolrCloud" page have been moved here (the latter being renamed to "SolrCloud Tutorial"). Screenshots below showing subsection list.

I did not try to improve any of the tutorial content, so if possible let's not discuss now about whether the exercises are appropriate or easy or whatever problems you have with them. It's not really relevant to this overall exercise IMO.

...

This allowed me to review all the places in the Ref Guide where we talk about "standalone mode"/"legacy"/"leader-follower" and make it clear what exactly we're talking about. I've introduced sentences like "In a user-managed cluster or a single-node installation..." in several contexts where previously we only talked about SolrCloud or referred to it as "legacy" or "standalone", etc.

I did it this way so we could discuss if anyone has serious objections to thinking of it this way as a project. And if so and we agree on some other phrasing, it will be easy to change.As an opinionated side note - I really hesitate to initiate a conversation about this. Every time it comes up we throw words up against the wall like a brainstorming session but we've "brainstormed" this for years with no forward movement and users are none the better for it. We need to just pick something and move forward with it, and that might mean some people just go with someone else's suggestion and not try to put up their own ideas.

Note I did not tackle renaming SolrCloud - that terminology is everywhere in the code (classnames, etc.), so until we do a project-wide change I think the docs should keep using it.

...

• New section layouts in "parent" pages (the ones that are mostly "here is what's in this section"). Where there are subsections of subsections the subsection list lives only on one page - the lowest level - and is tagged so it can be automatically included in all parent pages. This allows us to have descriptions consistent but maintained in only one place.
  • For example, the "Query Guide" has a subsection "Query Syntax and Parsing" which has several child pages. The "TOC" (as it were) is maintained on "Query Syntax and Parsing" and pulled into "Query Guide" only at build time.
  • This is also now in a table, and I've defined specific formatting for this purpose to display it in two columns instead of our previous long lists.
  • Multiple child page subsections have h3-level headers to differentiate them.
  • A couple of examples in screenshots below.
• All sentences start on new lines. I've missed some; IMO it's not a critical component, but can be continued ongoing.
• New format for parameters (only very partially done). See screenshots below.
• The icons in the left navbar are changed from arrows to + and - symbols.
• External links all now really open in new tabs (as has long been indicated by the icon that follows the URLs) (uses JS).
• Guide home page (index.adoc) redesigned a bit to take up less real estate (screenshot below). Download button has moved to top navbar as a link.
• Simplified the link text in top navbar "Resources" section; added "Contribute" to link to ref guide contribute docs in solr/dev-docs (TBD with SOLR-15458).
• Removed AnchorJS for section header anchor links and now use Asciidoctor's native 'sectanchors' functionality (which uses no javascript).

Screenshots