YES, YES, YES!!!!!!!
I think nearly everyone on this list will agree that getting started with
almost any open-source project is agony - it's just that we've all gotten
used to sucking it up and getting past it. Solr, given it's many moving
parts and multiple ways of doing things is "worse" than several other
projects I've dealt with in this sense.
Fortunately, I got paid to learn because my employer expected this from
open-source projects, so it was OK with me - although I did have many
hair-pulling moments in the first couple of months that would have been
totally eliminated by something like this.
One thing I'd like to suggest is that I believe the ideal tutorial does not
require someone to even install the software. So many open source projects
have tutorials that begin with:
"OK, now that you've figured out the incredibly complex and poorly
documented method of installing the software and getting it running, we'll
begin to explain how to use it..."
I'd suggest that a really good tutorial comes self-contained inside a VM or
Docker or AWS image (that can be cloned) so that interested people do not
have to even go through the install to start learning. I will also suggest
that running everything on the same machine on loopback is not really
helpful for learning how to make something work on separate servers or VM's
in production.
Of course, you want a "Solr Install Module" as part of the training - but
especially for people who want to learn about using SOLR and have a
production system, forcing them through a complete setup may not be the
best way...
My two cents worth anyway...
I have a number of years (long ago) in Tech writing and instructional
design. I enjoy building training materials. I'm happy to volunteer to be
a point person on this and build the docs and tutorials (with support from
the community) since I don't know it all by any means.
We could start with a proposed "table of contents" about what should be
covered and work from there.
On Thu, Sep 15, 2016 at 8:24 AM, Alexandre Rafalovitch <arafa...@gmail.com>
wrote:
> The WIKI may be an official community-contributing forum, but its
> technological implementation has gotten so bad it is impossible to
> update. Every time I change the page, it takes minutes (and feels like
> hours) for the update to come through. No clue what to do about that
> though.
>
> Creating the short, slim Solr User guide I feel should be in the same
> discussion as rewriting tutorials (shipped vs website ones) and
> shipped examples. One discussion, multiple ducks.
>
> I feel that it would be cool to have a live tutorial. Perhaps a
> special collection that, when bootstrapped from, provides tutorial,
> supporting data, smart interface to play with that data against that
> same instance, etc. It could also have a static read-only export, but
> the default experience should be interactive ("bin/solr start -e
> tutorial" or even "bin/solr start -e
> http://www.example.com/tutorial";....).
>
> And it should be something that very strongly focuses on teaching new
> users to fish, not just use the variety of seafood Solr comes with. A
> narrative showing how different parts of Solr come together and how to
> troubleshoot those, as opposed to taking each element (e.g. Query
> Parser) individually and covering them super-comprehensively. That
> last one is perfect in the reference guide, but less than friendly to
> a beginner.
>
> Regards,
> Alex.
>
>
>
> ----
> Newsletter and resources for Solr beginners and intermediates:
> http://www.solr-start.com/
>
>
> On 15 September 2016 at 20:24, john saylor <jsay...@brandeis.edu> wrote:
> > hey
> >
> > On 09/15/16 04:35, Jan Høydahl wrote:
> >>
> >> and the official user-contributed
> >> docs is at http://wiki.apache.org/solr/ <http://wiki.apache.org/solr/>
> >>
> >> But I wonder if we should consider creating an official, slim Solr User
> >> Guide
> >> as well, for end users, structured as a getting-started guide and with
> >> focus
> >> on how you achieve a task, not documenting all 99 parameters a plugin
> can
> >> take.
> >
> >
> > this sounds like a need to be filled.
> >
> > in another context (electronic music), the csound community created a
> floss
> > manual that i think has fulfilled many of these needs for them:
> > http://floss.booktype.pro/csound/preface/
> >
> > so maybe something like this could work for solr? i don't know a whole
> lot
> > about the software underlying the foss site, just a somewhat tangential
> > familiarity based upon consulting this resource and finding it answered
> my
> > questions pretty well.
> >
> > one size does not fit everyone.
>
