Allow Customisation of Elasticsearch Clients Landing page

[philkra]

It would be great if we could customise the (clients landing page).

At present, the page is generated from https://github.com/elastic/docs/blob/6dd5ec731a1bfcf6c6f2f0aaf8154bf2b815dd08/conf.yaml

...and presented to the user as a list of officially supported clients.

This is useful, but we would like to enhance this page to incorporate:

• Links to the Github repository for each client
• Links to the binaries/downloads for each client (e.g. Nuget packages for .NET client)
• Answers to common questions, for example:
  • What version of client and server can I use?
  • How do I upgrade the server and client? at the same time, client first, server first?
  • What is the roadmap / release schedule for feature X? When is version X being released?
  • What are the formats for the request and response bodies
• A list of community supported clients (or a link to the page) for popular languages
• Links to breaking changes documentation for each client?

Could we perhaps suggest the following:

1. Introduce a new index page in the docs repo to become the landing page.
2. In this new index page, insert an include file that will bring in the automatically generated list of officially supported clients (i.e. what we have already).
3. Give write access to this new index page to the clients team, so that they can make changes.

This would allow us to iterate quickly on the content and format of the page.

Does this sound feasible?

[debadair]

We don't, today, have a way to customize the landing pages in this way, or automatically overwrite the generated pages with hand-built ones. The doc workgroups have been discussing revamping the landing pages & we very much want to get there.

As a stop-gap, adding on to the build & publishing process to overwrite select pages with hand-curated ones doesn't seem like it would be terribly difficult. They'd have to be injected before the final link check is done, but managing a small set of pages this way until we have a less hacky solution doesn't seem too awful. (@gchaps and I proposed doing that for the main landing page almost a year ago?)

There's no backfill for @nik9000 yet, but if someone were motivated enough to dig into it, say, using the Client landing page as a proof of concept...it might lay the groundwork for a solution we can use without waiting until we can automagically generate curated landing pages.

I can see a couple concerns:

• Today, the doc nav (landing pages, TOCs) are strictly doc links. The proposed changes break that model. I'm less concerned about that today (it's pretty obvious what those links are to), but if that's not how we're thinking about the next-gen landing pages, we might not want to do this.

• Changing the UX repeatedly can be annoying, and larger changes are in the works. However, I think the delta between what's there now and what you're proposing is small enough that it isn't a big concern.

I've added this to the agenda for tomorrow's Docs UI working group meeting.

[codebrain]

Current redesign for docs is in progress, preview below.

Clicking on "Elasticsearch" on left nav opens the Elasticsearch landing page, and scrolling down we see clients (highlighted in green box):

The current discussion with @debadair is how the "all clients" landing
page works; is the CLIENTS title (highlighted in orange) clickable? or should we insert a "Introduction to Elasticsearch Clients" menu item under the CLIENTS title? Debate is still open on this topic as the design is still a work in progress.

The official client languages (highlighted in the green box) are clickable, and each one should then open a client-specific landing page in the main content window. This landing page would contain a customizable section and I believe will serve as a good place to put repository links, download links, common questions/answers, breaking changes docs etc. Given each official client has different needs I think we need to give each developer enough flexibility to add their own headers/sections/text as they see fit and then manage any commonality ourselves within the clients team using conformance tickets. I think prescribing titles and sections for each client in the code template isn't a good idea.

If unofficial clients are listed in the green box (or on the "all clients" landing page) then clicking on one ought to open the repository for that client. We will not be maintaining landing pages for each unofficial client.

@philkra

[Adrian-J]

@codebrain The grey labels in the nav are not clickable. These are there to group the pages in a logical way and improve the navigation. If you'd like to have a landing page for clients I recommend adding another link at the top of the list. Let me know if I can help in any way. I'm happy to prototype this landing page if you have a general outline in mind.

[gtback]

A big features of the redesign is that there will be persistent navigation on the left side of the screen. So, pages like this one will need to just go away IMO. I think the following pages can be used as the "landing page" for each of the clients (and of course the client developers can modify them as needed).

• Java REST Client
• Java API
• Elasticsearch Node.js client
• Ruby And Rails Integrations
• Go API
• Elasticsearch.Net and NEST: the .NET clients. Or possibly split directly into:
  • Elasticsearch.Net - Low level client
  • NEST - High level client
• PHP API
• Perl API
• Python API
• eland Client
• Rust API

[philkra]

I think we lost the original ask in lieu of the discussion and redesign. We would like to customise this page to provide shared docs and e.g. links directly to corresponding github repo. Do such landing pages still exist in the redesign and/or how can we incorporate this?

[codebrain]

@gtback I think we ought to group like this:

• .NET clients
  • Elasticsearch.Net - Low level client
  • NEST - High level client

[codebrain]

I think we lost the original ask in lieu of the discussion and redesign. We would like to customise this page to provide shared docs and e.g. links directly to corresponding github repo. Do such landing pages still exist in the redesign and/or how can we incorporate this?

My understanding from Deb is that the main landing page link (highlighted in the orange box below) would go to an "all clients" landing page:

So with this redesign we get an "all clients" landing page from the main landing page (as shown above) and a landing page for each client.

[gtback]

@philkra sorry, I didn't read the full history of the thread. Yes, we don't have a good way to override the default "table of contents" pages, but will be exploring doing that as part of the redesign.

The alternative (if it's more urgent) would be to create a small, separate "clients" book that itself would link to the existing books, but that would require some extra redirects that we probably want to avoid unless this is needed sooner.

[philkra]

@Adrian-J and @gtback based on our chat yesterday, I compiled a document with items for the landing page: https://docs.google.com/document/d/1nIuy8KAhaVZ1dXFzOOjJ_DQZNZrng3Rp68zBt9V5B4o/edit#
/cc @Mpdreamz @sethpayne