Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Revamp Elasticsearch getting started topic #43721

Open
debadair opened this issue Jun 28, 2019 · 3 comments

Comments

@debadair
Copy link
Contributor

commented Jun 28, 2019

Although 71 contributors have made updates to getting-started.asciidoc over the last 5 years, its overall content and structure haven't changed much since it was first written. In Elastic years, 5 years is a very long time.

I'm proposing to tear it apart and rebuild it to be... Better...stronger...faster.

The purpose

Get folks who are new to Elasticsearch up, running, and trying things out so they can see how Elasticsearch works.

The audience

If you have a general sense of what Elasticsearch is and the inclination to start tinkering, this topic will help you do that.

What it is...and isn't

It's a lightweight, easy-to-follow, hands-on tutorial for new users. It isn't a comprehensive set up guide and doesn't need to teach users how to "do it all". It isn't about how to use Elasticsearch for a particular purpose, it's intended to help users understand how Elasticsearch works and highlight the characteristics that make it suitable for a variety of use cases.

What needs to be done

  • Streamline the intro. The Elasticsearch introduction now provides a general overview of Elasticsearch and introduces the key concepts, so a summary here will suffice.
  • Simplify the quick set up instructions (#45009). It's okay to gloss over the caveats and alternatives, we have complete Installation instructions.
  • Mirror the structure of the introduction. (#45527)
  • Streamline the indexing section. (#45714)
  • Streamline the content to focus on how to get data in, retrieve documents, and construct queries and aggregations to get information out.

Other considerations

  • This is an oft-linked-to, high-traffic topic. The top-level page name cannot change, and redirects must be set up for any sub-pages that are removed.
  • This topic should be as self-contained as possible. Minimize the number of clicks to get to the end, and avoid cross-links that send users out of the flow of the tutorial.
  • Once the tutorial content is updated, we can incorporate a short video run-through.

@debadair debadair added the >docs label Jun 28, 2019

@debadair debadair self-assigned this Jun 28, 2019

@elasticmachine

This comment has been minimized.

Copy link
Collaborator

commented Jun 28, 2019

@alaudazzi

This comment has been minimized.

Copy link

commented Jun 28, 2019

This is a great plan, @debadair!
Happy to contribute, in particular for the short video integration, as I am already working on a video-related issue #32109.

@jrodewig

This comment has been minimized.

Copy link
Contributor

commented Jun 28, 2019

Mirror the structure of the introduction. Demonstrate how to get data in, retrieve documents, and construct queries and aggregations to get information out.

You may be able to mine https://github.com/elastic/elasticsearch/pull/40903/files#diff-d9b40c6d43a0f89c103f76bab86b647c for some content.

The only thing missing would be an agg example.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.