[
https://issues.apache.org/jira/browse/SOLR-14726?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17174174#comment-17174174
]
Jan Høydahl commented on SOLR-14726:
------------------------------------
The "let's rip out everything that we don't recommend in production" strategy
is somewhat misguided I think. Why shuold the first step of a tutorial be how
to enable authentication? Or SSL? Or replication? It's OK to learn the basics
of a search engine without any of those. But I agree we don't need to teach
users tools or practices that they will not be able to use at their job, such
as {{bin/solr -e foo}} examples. I also agree it's time to start promoting v2
apis and REST commands for schema modification etc.
I love the idea of finding/creating a dataset that can be used throughout our
examples. Something that is realistic, possible to ship a small cut-down sample
with Solr, as well as ability to download a richer and larger version for more
advanced turorials, such as MLT, Parent/Child, Streaming, ML etc.
The bin/post (SimplePostTool) was originally a small Java class to teach Java
devs how to integrate with Solr without any dependencies, not even SolrJ. Being
the only HTTP post tool you could rely on everywhere, it was used in examples.
However, the java -jar post.jar -Dfoo=bar invocation became too complex, so a
wrapper script was invented. Then batch indexing was added exactly for the
purpose of getting users from download to a searchable index as quickly as
possible. Which is important to not lose interest. Perhaps we did a too good
job there, so some users were tempted to use the tool in production :) There is
still no single http post tool for all platforms, but asking users to install
cURL to do a tutorial is probably not too much to ask anyway, so +1 to more
cURL in our docs.
Before we kill bin/post, ideally we get started with a Solr SDK with a set of
code samples that demonstrate how to do what bin/post typically does. Imagine
if we could ship working code samples with tests, in Java and Python and at the
same time demonstrate best practices. And you get a new post tool as a
bi-product, that users can modify!
+1 also to Docker instructions.
> Streamline getting started experience
> -------------------------------------
>
> Key: SOLR-14726
> URL: https://issues.apache.org/jira/browse/SOLR-14726
> Project: Solr
> Issue Type: Task
> Security Level: Public(Default Security Level. Issues are Public)
> Reporter: Ishan Chattopadhyaya
> Priority: Major
> Labels: newdev
>
> The reference guide Solr tutorial is here:
> https://lucene.apache.org/solr/guide/8_6/solr-tutorial.html
> It needs to be simplified and easy to follow. Also, it should reflect our
> best practices, that should also be followed in production. I have following
> suggestions:
> # Make it less verbose. It is too long. On my laptop, it required 35 page
> downs button presses to get to the bottom of the page!
> # First step of the tutorial should be to enable security (basic auth should
> suffice).
> # {{./bin/solr start -e cloud}} <-- All references of -e should be removed.
> # All references of {{bin/solr post}} to be replaced with {{curl}}
> # Convert all {{bin/solr create}} references to curl of collection creation
> commands
> # Add docker based startup instructions.
> # Create a Jupyter Notebook version of the entire tutorial, make it so that
> it can be easily executed from Google Colaboratory. Here's an example:
> https://twitter.com/TheSearchStack/status/1289703715981496320
> # Provide downloadable Postman and Insomnia files so that the same tutorial
> can be executed from those tools. Except for starting Solr, all other steps
> should be possible to be carried out from those tools.
> # Use V2 APIs everywhere in the tutorial
> # Remove all example modes, sample data (films, tech products etc.),
> configsets from Solr's distribution (instead let the examples refer to them
> from github)
> # Remove the post tool from Solr, curl should suffice.
--
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
