Solr Ref Guide vs. Wiki

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Solr Ref Guide vs. Wiki

Grant Ingersoll-2
Hi,

Main question:  Should we
[] Lock down the Solr Wiki sooner rather than later and put all focus on adding to and improving the Ref Guide
[] Leave the wiki open for anyone to edit now and selectively go through and try to reconcile it (and delete as we move) and encourage people to go to the ref guide.   (in other words, continue as is)

Background:

I'm in a position to deploy some resources to work on Solr's documentation a bit more.  Namely, I'd like to close the gaps/differences/discrepancies between the wiki and the ref guide.  I know Hoss, Cassandra and others have come up with a plan for addressing these gaps by going through the pages, highlighting the diffs and reconciling them in the ref guide and then removing from the wiki, with the goal being that the Ref Guide is the one and only authoritative documentation and the wiki is solely for uncurated user tips, tricks and ideas.

Before doing that, however, I think it is worth asking the question:  What if we just "ripped off the band-aid" instead and simply archived the wiki (move all the current content to an archive area on the wiki and mark that area as read only) and change the landing page to refer all documentation questions to the Ref Guide and the Wiki should simply be tips, tricks, etc. and is NOT official documentation and committers, for the most part, don't worry about curating content there.  We'd need to put in the appropriate redirects (or at least some redirects) as well, but otherwise, not worry about reconciling things but instead focus on going through the Ref Guide and simply adding to it "fresh" without worry about what is on the wiki. 

My gut says Google will recrawl/update to the Ref Guide as the authoritative version pretty quickly and the rest of the world will follow suit soon thereafter.  Naturally, we'd lose some of the links from places like StackOverflow, etc. but if we redirect appropriately, we could minimize the pain of this.

Naturally, I can still focus resources on just doing the ref guide and leave others to do the cross referencing, but I think it is important that we try to come to some level of agreement on what to do w/ the old content, hence the email to gather other people's opinions.  

-Grant
--------------------------------------------
Grant Ingersoll | @gsingers
http://www.lucidworks.com





Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Yonik Seeley-5
On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]> wrote:
> Lock down the Solr Wiki
[...]
> the Wiki should simply be tips, tricks, etc. and is NOT official documentation and committers, for the most part, don't worry about curating content there.

These two things seem incompatible.  If wiki pages on tips, tricks,
etc continue to be permitted, how does one "Lock down the Solr Wiki"?

-Yonik
http://heliosearch.org - solve Solr GC pauses with off-heap filters
and fieldcache

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Grant Ingersoll-2

On Apr 3, 2014, at 6:57 PM, Yonik Seeley <[hidden email]> wrote:

On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]> wrote:
Lock down the Solr Wiki
[...]
the Wiki should simply be tips, tricks, etc. and is NOT official documentation and committers, for the most part, don't worry about curating content there.

These two things seem incompatible.  If wiki pages on tips, tricks,
etc continue to be permitted, how does one "Lock down the Solr Wiki"?

I mean lock down the current stuff, move it to an archive area (see if we can make it read-only) and replace the landing page with just the community/tips/tricks sections that are there.


-Yonik
http://heliosearch.org - solve Solr GC pauses with off-heap filters
and fieldcache

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--------------------------------------------
Grant Ingersoll | @gsingers
http://www.lucidworks.com





Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Mark Miller-3
I’m not too worried about locking anything down, but the current situation is quite confusing. It can be hard to tell what docs you should be looking at for a new user.

I’ve started putting big warnings and links on a couple important pages for the old Wiki, but we should really a do a lot more to make it clear that the old wiki system is not our documentation. All signs should point to cwiki.

-- 
Mark Miller
about.me/markrmiller

On April 4, 2014 at 9:46:02 AM, Grant Ingersoll ([hidden email]) wrote:


On Apr 3, 2014, at 6:57 PM, Yonik Seeley <[hidden email]> wrote:

On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]> wrote:
Lock down the Solr Wiki
[...]
the Wiki should simply be tips, tricks, etc. and is NOT official documentation and committers, for the most part, don't worry about curating content there.

These two things seem incompatible.  If wiki pages on tips, tricks,
etc continue to be permitted, how does one "Lock down the Solr Wiki"?

I mean lock down the current stuff, move it to an archive area (see if we can make it read-only) and replace the landing page with just the community/tips/tricks sections that are there.


-Yonik
http://heliosearch.org - solve Solr GC pauses with off-heap filters
and fieldcache

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


--------------------------------------------
Grant Ingersoll | @gsingers
http://www.lucidworks.com





Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Alexandre Rafalovitch
+1 on consolidating to the Reference Guide and figuring out the way to
make wiki a lot less visible. But for a completely different set of
reasons than discussed already.

[[rant-start]]

I think an interesting side-effect issue here is user perception. I
feel that ElasticSearch (yet, them) get a lot of points not only
because of features (not discussing that here) but because they
actually have taken time to put a polish on the SEO, onboarding and
other human perception aspects.

Solr's messaging is - like many of Apache projects - deeply technical,
self-referential and on the main path puts Development before Use
(literally, by the order of the wiki sections). Which is _no longer_
representative of the users' needs.

Reference guide is a large step in the right direction. Commercial
distributions also do their best to do the messaging right, even if
often at the expense of pushing Solr into an implementation detail
(Cloudera!).

But I think this is a case of the tide raising all (Solr-based) boats.
Somebody with UX skills can probably deconstruct and reconstruct the
user experience and the same information will have a lot more impact.

This even applies to technical issues as well. Elastic Search has
great success talking about schema-less design and Solr relegates its
equivalence to a small section deep in the Wiki/Guide. Same with
real-time updates. That's because the site/documentation is organized
from the implementation rather than impact points of view.

If somebody has resources to throw at this, I would start from the UX
and user-onboarding part. Maybe even do that for both Lucene and Solr
to emphasize common links. And I would be happy to work with someone
on that too. Maybe, there is even a need for a separate
super-duper-happy-solr-path mailing group to specialize on that.
Something that commercial companies can temporarily throw other
non-dev resources at, when required.

[[rant-end]]

Regards,
   Alex.
P.s. There is a LOT more to the rant, with specific suggestions. And I
am walking my talk too (book, solr-start, my nascent mailing list, and
a ToDo list to last me next several years of fun projects).

Personal website: http://www.outerthoughts.com/
Current project: http://www.solr-start.com/ - Accelerating your Solr proficiency

On Fri, Apr 4, 2014 at 9:09 PM, Mark Miller <[hidden email]> wrote:

> I’m not too worried about locking anything down, but the current situation
> is quite confusing. It can be hard to tell what docs you should be looking
> at for a new user.
>
> I’ve started putting big warnings and links on a couple important pages for
> the old Wiki, but we should really a do a lot more to make it clear that the
> old wiki system is not our documentation. All signs should point to cwiki.
>
> --
> Mark Miller
> about.me/markrmiller
>
> On April 4, 2014 at 9:46:02 AM, Grant Ingersoll ([hidden email]) wrote:
>
>
> On Apr 3, 2014, at 6:57 PM, Yonik Seeley <[hidden email]> wrote:
>
> On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]> wrote:
>
> Lock down the Solr Wiki
>
> [...]
>
> the Wiki should simply be tips, tricks, etc. and is NOT official
> documentation and committers, for the most part, don't worry about curating
> content there.
>
>
> These two things seem incompatible.  If wiki pages on tips, tricks,
> etc continue to be permitted, how does one "Lock down the Solr Wiki"?
>
>
> I mean lock down the current stuff, move it to an archive area (see if we
> can make it read-only) and replace the landing page with just the
> community/tips/tricks sections that are there.
>
>
> -Yonik
> http://heliosearch.org - solve Solr GC pauses with off-heap filters
> and fieldcache
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
> --------------------------------------------
> Grant Ingersoll | @gsingers
> http://www.lucidworks.com
>
>
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

kamaci
I think an interesting side-effect issue here is user perception. I
| feel that ElasticSearch (yet, them) get a lot of points not only
| because of features (not discussing that here) but because they
| actually have taken time to put a polish on the SEO, onboarding and
| other human perception aspects.

that is exactly true. Search that on Google: solr search parameters and have a look at the results. Then search that: elasticsearch search parameters. You can feel that there has been done a work for SEO at elasticsearch side.

When I started to learn Solr I read every thing, every thing that I can find. These include Solr wiki, books, websites about Solr and every e-mail at mail list. However is it usual that there were still some pages at wiki that I've not seen it before. I've clicked every link at wiki but there was some hidden(!) pages that I could not achieve to see it. For example every body knows that Shawn has a page tells something about GC tunning for Solr. Do you know that how to reach that page when you start to read the wiki?

Reference guide is pretty good. It is like a book for Solr. You start to read and when you finish it you get a good knowledge about Solr. My suggestion is that: We can rich the Solr guide with links to some external pages if it is necessary. On the other hand we can design a nice web site that explains Solr feautures as like elasticsearch.

I "personally" separate people into four main categories who works with Solr:

First category: He uses Solr, wants to improve search performance, tunning etc. etc. but do not know the implementation details very much.
Second category: He is interesting about scalability, tunning etc. of Solr.
Third category: He is interesting about linguistic/search part of Solr (Lucene).
Forth category: He is interesting about developing Solr.

So, a wiki should point to the people who uses it, who wants to operate it, who wants to improve search benefit and who wants to develop it. My personal idea is that: first category is very important too. When you read the guide of Elasticsearch it is simple and explains the main things (i.e. you can compare the analyzer page at Elasticsearch and Solr). People want to startup a system and do not want to do much more thing (I know it is impossible). We can help address to such kind of audience too (I know that Solr and Elasticsearch audince are not same). I mean a web page explains Solr as like elasticsearch and a guide (with links to other resources) that addresses to both four category would be nice.

All in all I would want to help Solr for such kind of documentation (I can work with Alexandre collaboratively). It would be nice if we have something like that.

Thanks;
Furkan KAMACI



2014-04-05 6:21 GMT+03:00 Alexandre Rafalovitch <[hidden email]>:
+1 on consolidating to the Reference Guide and figuring out the way to
make wiki a lot less visible. But for a completely different set of
reasons than discussed already.

[[rant-start]]

I think an interesting side-effect issue here is user perception. I
feel that ElasticSearch (yet, them) get a lot of points not only
because of features (not discussing that here) but because they
actually have taken time to put a polish on the SEO, onboarding and
other human perception aspects.

Solr's messaging is - like many of Apache projects - deeply technical,
self-referential and on the main path puts Development before Use
(literally, by the order of the wiki sections). Which is _no longer_
representative of the users' needs.

Reference guide is a large step in the right direction. Commercial
distributions also do their best to do the messaging right, even if
often at the expense of pushing Solr into an implementation detail
(Cloudera!).

But I think this is a case of the tide raising all (Solr-based) boats.
Somebody with UX skills can probably deconstruct and reconstruct the
user experience and the same information will have a lot more impact.

This even applies to technical issues as well. Elastic Search has
great success talking about schema-less design and Solr relegates its
equivalence to a small section deep in the Wiki/Guide. Same with
real-time updates. That's because the site/documentation is organized
from the implementation rather than impact points of view.

If somebody has resources to throw at this, I would start from the UX
and user-onboarding part. Maybe even do that for both Lucene and Solr
to emphasize common links. And I would be happy to work with someone
on that too. Maybe, there is even a need for a separate
super-duper-happy-solr-path mailing group to specialize on that.
Something that commercial companies can temporarily throw other
non-dev resources at, when required.

[[rant-end]]

Regards,
   Alex.
P.s. There is a LOT more to the rant, with specific suggestions. And I
am walking my talk too (book, solr-start, my nascent mailing list, and
a ToDo list to last me next several years of fun projects).

Personal website: http://www.outerthoughts.com/
Current project: http://www.solr-start.com/ - Accelerating your Solr proficiency

On Fri, Apr 4, 2014 at 9:09 PM, Mark Miller <[hidden email]> wrote:
> I’m not too worried about locking anything down, but the current situation
> is quite confusing. It can be hard to tell what docs you should be looking
> at for a new user.
>
> I’ve started putting big warnings and links on a couple important pages for
> the old Wiki, but we should really a do a lot more to make it clear that the
> old wiki system is not our documentation. All signs should point to cwiki.
>
> --
> Mark Miller
> about.me/markrmiller
>
> On April 4, 2014 at 9:46:02 AM, Grant Ingersoll ([hidden email]) wrote:
>
>
> On Apr 3, 2014, at 6:57 PM, Yonik Seeley <[hidden email]> wrote:
>
> On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]> wrote:
>
> Lock down the Solr Wiki
>
> [...]
>
> the Wiki should simply be tips, tricks, etc. and is NOT official
> documentation and committers, for the most part, don't worry about curating
> content there.
>
>
> These two things seem incompatible.  If wiki pages on tips, tricks,
> etc continue to be permitted, how does one "Lock down the Solr Wiki"?
>
>
> I mean lock down the current stuff, move it to an archive area (see if we
> can make it read-only) and replace the landing page with just the
> community/tips/tricks sections that are there.
>
>
> -Yonik
> http://heliosearch.org - solve Solr GC pauses with off-heap filters
> and fieldcache
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
> --------------------------------------------
> Grant Ingersoll | @gsingers
> http://www.lucidworks.com
>
>
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Grant Ingersoll-2
While I somewhat agree with both the points of Furkan and Alexandre, I am not sure which way you are leaning:  Should we pull off the band-aid or not?  And do no other committers have an opinion here?

-Grant

On Apr 5, 2014, at 6:25 PM, Furkan KAMACI <[hidden email]> wrote:

I think an interesting side-effect issue here is user perception. I
| feel that ElasticSearch (yet, them) get a lot of points not only
| because of features (not discussing that here) but because they
| actually have taken time to put a polish on the SEO, onboarding and
| other human perception aspects.

that is exactly true. Search that on Google: solr search parameters and have a look at the results. Then search that: elasticsearch search parameters. You can feel that there has been done a work for SEO at elasticsearch side.

When I started to learn Solr I read every thing, every thing that I can find. These include Solr wiki, books, websites about Solr and every e-mail at mail list. However is it usual that there were still some pages at wiki that I've not seen it before. I've clicked every link at wiki but there was some hidden(!) pages that I could not achieve to see it. For example every body knows that Shawn has a page tells something about GC tunning for Solr. Do you know that how to reach that page when you start to read the wiki?

Reference guide is pretty good. It is like a book for Solr. You start to read and when you finish it you get a good knowledge about Solr. My suggestion is that: We can rich the Solr guide with links to some external pages if it is necessary. On the other hand we can design a nice web site that explains Solr feautures as like elasticsearch.

I "personally" separate people into four main categories who works with Solr:

First category: He uses Solr, wants to improve search performance, tunning etc. etc. but do not know the implementation details very much.
Second category: He is interesting about scalability, tunning etc. of Solr.
Third category: He is interesting about linguistic/search part of Solr (Lucene).
Forth category: He is interesting about developing Solr.

So, a wiki should point to the people who uses it, who wants to operate it, who wants to improve search benefit and who wants to develop it. My personal idea is that: first category is very important too. When you read the guide of Elasticsearch it is simple and explains the main things (i.e. you can compare the analyzer page at Elasticsearch and Solr). People want to startup a system and do not want to do much more thing (I know it is impossible). We can help address to such kind of audience too (I know that Solr and Elasticsearch audince are not same). I mean a web page explains Solr as like elasticsearch and a guide (with links to other resources) that addresses to both four category would be nice.

All in all I would want to help Solr for such kind of documentation (I can work with Alexandre collaboratively). It would be nice if we have something like that.

Thanks;
Furkan KAMACI



2014-04-05 6:21 GMT+03:00 Alexandre Rafalovitch <[hidden email]>:
+1 on consolidating to the Reference Guide and figuring out the way to
make wiki a lot less visible. But for a completely different set of
reasons than discussed already.

[[rant-start]]

I think an interesting side-effect issue here is user perception. I
feel that ElasticSearch (yet, them) get a lot of points not only
because of features (not discussing that here) but because they
actually have taken time to put a polish on the SEO, onboarding and
other human perception aspects.

Solr's messaging is - like many of Apache projects - deeply technical,
self-referential and on the main path puts Development before Use
(literally, by the order of the wiki sections). Which is _no longer_
representative of the users' needs.

Reference guide is a large step in the right direction. Commercial
distributions also do their best to do the messaging right, even if
often at the expense of pushing Solr into an implementation detail
(Cloudera!).

But I think this is a case of the tide raising all (Solr-based) boats.
Somebody with UX skills can probably deconstruct and reconstruct the
user experience and the same information will have a lot more impact.

This even applies to technical issues as well. Elastic Search has
great success talking about schema-less design and Solr relegates its
equivalence to a small section deep in the Wiki/Guide. Same with
real-time updates. That's because the site/documentation is organized
from the implementation rather than impact points of view.

If somebody has resources to throw at this, I would start from the UX
and user-onboarding part. Maybe even do that for both Lucene and Solr
to emphasize common links. And I would be happy to work with someone
on that too. Maybe, there is even a need for a separate
super-duper-happy-solr-path mailing group to specialize on that.
Something that commercial companies can temporarily throw other
non-dev resources at, when required.

[[rant-end]]

Regards,
   Alex.
P.s. There is a LOT more to the rant, with specific suggestions. And I
am walking my talk too (book, solr-start, my nascent mailing list, and
a ToDo list to last me next several years of fun projects).

Personal website: http://www.outerthoughts.com/
Current project: http://www.solr-start.com/ - Accelerating your Solr proficiency

On Fri, Apr 4, 2014 at 9:09 PM, Mark Miller <[hidden email]> wrote:
> I’m not too worried about locking anything down, but the current situation
> is quite confusing. It can be hard to tell what docs you should be looking
> at for a new user.
>
> I’ve started putting big warnings and links on a couple important pages for
> the old Wiki, but we should really a do a lot more to make it clear that the
> old wiki system is not our documentation. All signs should point to cwiki.
>
> --
> Mark Miller
> about.me/markrmiller
>
> On April 4, 2014 at 9:46:02 AM, Grant Ingersoll ([hidden email]) wrote:
>
>
> On Apr 3, 2014, at 6:57 PM, Yonik Seeley <[hidden email]> wrote:
>
> On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]> wrote:
>
> Lock down the Solr Wiki
>
> [...]
>
> the Wiki should simply be tips, tricks, etc. and is NOT official
> documentation and committers, for the most part, don't worry about curating
> content there.
>
>
> These two things seem incompatible.  If wiki pages on tips, tricks,
> etc continue to be permitted, how does one "Lock down the Solr Wiki"?
>
>
> I mean lock down the current stuff, move it to an archive area (see if we
> can make it read-only) and replace the landing page with just the
> community/tips/tricks sections that are there.
>
>
> -Yonik
> http://heliosearch.org - solve Solr GC pauses with off-heap filters
> and fieldcache
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
> --------------------------------------------
> Grant Ingersoll | @gsingers
> http://www.lucidworks.com
>
>
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



--------------------------------------------
Grant Ingersoll | @gsingers
http://www.lucidworks.com





Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Shawn Heisey-4
On 4/6/2014 4:12 AM, Grant Ingersoll wrote:
> While I somewhat agree with both the points of Furkan and Alexandre, I
> am not sure which way you are leaning:  Should we pull off the band-aid
> or not?  And do no other committers have an opinion here?

One of the strengths (and weaknesses!) of the old wiki is that anyone
who asks for permission is allowed to edit it. If I filter my email
archive for 'wikidiffs' so I can see old wiki change notifications, most
of the changes in the last year have come from committers.  It would be
incorrect to state that non-committer contributions are completely
trivial, though.  A few of them have been very active.

Only committers can change the reference guide ... which is reasonable
because it's published as official documentation.

I am inclined to vote that we take these steps:

1) Lock down the old wiki, at least temporarily.
2) Improve the SEO of the reference guide.
3) Beef up the reference guide with *relevant* info from the wiki.

Further steps will require some thought.

For wiki pages which directly correspond to reference guide pages, it's
reasonable and appropriate to phase them out after making sure that
everything important gets transferred to the reference guide.

There is other content in the wiki, though.  One of my larger
contributions to the old wiki is the page about performance problems.
While I do think this an appropriate topic to put in the reference
guide, there might be things stated there that the project does not want
to declare in an official voice.  I like to think that those things are
important, so I'd hate to see them disappear entirely.

http://wiki.apache.org/solr/SolrPerformanceProblems

Perhaps we can re-purpose the old wiki into a supplement to the
reference guide, once again open to modification by contributors.
Tips/tricks and information that's not suitable for official
documentation can live there.  This MIGHT make it a natural staging
ground for improvements and large-scale changes to the reference guide,
both from the community and committers.

Thanks,
Shawn


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Erick Erickson
In reply to this post by Grant Ingersoll-2
+1 to making the CWiki the One True Source (tm) for Solr documentation.

Rip the damn band-aid off. Deal with the screams by asking anyone with
a beef to contribute to the CWiki. Not quite sure the mechanism here
though. Maybe Cassandra and Hoss have some thoughts here?

The point is that I want to make the burden on the maintainers of the
CWiki as light as possible in terms of adding new content. Currently,
there's a lightweight mechanism for people to add to the Wiki. I'm
thinking we wouldn't open up the CWiki the same way, but could we
maybe have a "scratch pad" area where volunteers could create pages
that could be copy/pasted into the CWiki? For instance, the analytics
component has a bunch of documentation with it. How can we incorporate
it as painlessly as possible?

Locking down the Wiki would add to the message that the Wiki wasn't
where the action is. We still need the "tips and tricks" section.
Hmmm, how about "tips, tricks, and the best of the user's list"?

FWIW,
Erick



On Sun, Apr 6, 2014 at 3:12 AM, Grant Ingersoll <[hidden email]> wrote:

> While I somewhat agree with both the points of Furkan and Alexandre, I am
> not sure which way you are leaning:  Should we pull off the band-aid or not?
> And do no other committers have an opinion here?
>
> -Grant
>
> On Apr 5, 2014, at 6:25 PM, Furkan KAMACI <[hidden email]> wrote:
>
> | I think an interesting side-effect issue here is user perception. I
> | feel that ElasticSearch (yet, them) get a lot of points not only
> | because of features (not discussing that here) but because they
> | actually have taken time to put a polish on the SEO, onboarding and
> | other human perception aspects.
>
> that is exactly true. Search that on Google: solr search parameters and have
> a look at the results. Then search that: elasticsearch search parameters.
> You can feel that there has been done a work for SEO at elasticsearch side.
>
> When I started to learn Solr I read every thing, every thing that I can
> find. These include Solr wiki, books, websites about Solr and every e-mail
> at mail list. However is it usual that there were still some pages at wiki
> that I've not seen it before. I've clicked every link at wiki but there was
> some hidden(!) pages that I could not achieve to see it. For example every
> body knows that Shawn has a page tells something about GC tunning for Solr.
> Do you know that how to reach that page when you start to read the wiki?
>
> Reference guide is pretty good. It is like a book for Solr. You start to
> read and when you finish it you get a good knowledge about Solr. My
> suggestion is that: We can rich the Solr guide with links to some external
> pages if it is necessary. On the other hand we can design a nice web site
> that explains Solr feautures as like elasticsearch.
>
> I "personally" separate people into four main categories who works with
> Solr:
>
> First category: He uses Solr, wants to improve search performance, tunning
> etc. etc. but do not know the implementation details very much.
> Second category: He is interesting about scalability, tunning etc. of Solr.
> Third category: He is interesting about linguistic/search part of Solr
> (Lucene).
> Forth category: He is interesting about developing Solr.
>
> So, a wiki should point to the people who uses it, who wants to operate it,
> who wants to improve search benefit and who wants to develop it. My personal
> idea is that: first category is very important too. When you read the guide
> of Elasticsearch it is simple and explains the main things (i.e. you can
> compare the analyzer page at Elasticsearch and Solr). People want to startup
> a system and do not want to do much more thing (I know it is impossible). We
> can help address to such kind of audience too (I know that Solr and
> Elasticsearch audince are not same). I mean a web page explains Solr as like
> elasticsearch and a guide (with links to other resources) that addresses to
> both four category would be nice.
>
> All in all I would want to help Solr for such kind of documentation (I can
> work with Alexandre collaboratively). It would be nice if we have something
> like that.
>
> Thanks;
> Furkan KAMACI
>
>
>
> 2014-04-05 6:21 GMT+03:00 Alexandre Rafalovitch <[hidden email]>:
>>
>> +1 on consolidating to the Reference Guide and figuring out the way to
>> make wiki a lot less visible. But for a completely different set of
>> reasons than discussed already.
>>
>> [[rant-start]]
>>
>> I think an interesting side-effect issue here is user perception. I
>> feel that ElasticSearch (yet, them) get a lot of points not only
>> because of features (not discussing that here) but because they
>> actually have taken time to put a polish on the SEO, onboarding and
>> other human perception aspects.
>>
>> Solr's messaging is - like many of Apache projects - deeply technical,
>> self-referential and on the main path puts Development before Use
>> (literally, by the order of the wiki sections). Which is _no longer_
>> representative of the users' needs.
>>
>> Reference guide is a large step in the right direction. Commercial
>> distributions also do their best to do the messaging right, even if
>> often at the expense of pushing Solr into an implementation detail
>> (Cloudera!).
>>
>> But I think this is a case of the tide raising all (Solr-based) boats.
>> Somebody with UX skills can probably deconstruct and reconstruct the
>> user experience and the same information will have a lot more impact.
>>
>> This even applies to technical issues as well. Elastic Search has
>> great success talking about schema-less design and Solr relegates its
>> equivalence to a small section deep in the Wiki/Guide. Same with
>> real-time updates. That's because the site/documentation is organized
>> from the implementation rather than impact points of view.
>>
>> If somebody has resources to throw at this, I would start from the UX
>> and user-onboarding part. Maybe even do that for both Lucene and Solr
>> to emphasize common links. And I would be happy to work with someone
>> on that too. Maybe, there is even a need for a separate
>> super-duper-happy-solr-path mailing group to specialize on that.
>> Something that commercial companies can temporarily throw other
>> non-dev resources at, when required.
>>
>> [[rant-end]]
>>
>> Regards,
>>    Alex.
>> P.s. There is a LOT more to the rant, with specific suggestions. And I
>> am walking my talk too (book, solr-start, my nascent mailing list, and
>> a ToDo list to last me next several years of fun projects).
>>
>> Personal website: http://www.outerthoughts.com/
>> Current project: http://www.solr-start.com/ - Accelerating your Solr
>> proficiency
>>
>> On Fri, Apr 4, 2014 at 9:09 PM, Mark Miller <[hidden email]> wrote:
>> > I'm not too worried about locking anything down, but the current
>> > situation
>> > is quite confusing. It can be hard to tell what docs you should be
>> > looking
>> > at for a new user.
>> >
>> > I've started putting big warnings and links on a couple important pages
>> > for
>> > the old Wiki, but we should really a do a lot more to make it clear that
>> > the
>> > old wiki system is not our documentation. All signs should point to
>> > cwiki.
>> >
>> > --
>> > Mark Miller
>> > about.me/markrmiller
>> >
>> > On April 4, 2014 at 9:46:02 AM, Grant Ingersoll ([hidden email])
>> > wrote:
>> >
>> >
>> > On Apr 3, 2014, at 6:57 PM, Yonik Seeley <[hidden email]> wrote:
>> >
>> > On Thu, Apr 3, 2014 at 6:24 PM, Grant Ingersoll <[hidden email]>
>> > wrote:
>> >
>> > Lock down the Solr Wiki
>> >
>> > [...]
>> >
>> > the Wiki should simply be tips, tricks, etc. and is NOT official
>> > documentation and committers, for the most part, don't worry about
>> > curating
>> > content there.
>> >
>> >
>> > These two things seem incompatible.  If wiki pages on tips, tricks,
>> > etc continue to be permitted, how does one "Lock down the Solr Wiki"?
>> >
>> >
>> > I mean lock down the current stuff, move it to an archive area (see if
>> > we
>> > can make it read-only) and replace the landing page with just the
>> > community/tips/tricks sections that are there.
>> >
>> >
>> > -Yonik
>> > http://heliosearch.org - solve Solr GC pauses with off-heap filters
>> > and fieldcache
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: [hidden email]
>> > For additional commands, e-mail: [hidden email]
>> >
>> >
>> > --------------------------------------------
>> > Grant Ingersoll | @gsingers
>> > http://www.lucidworks.com
>> >
>> >
>> >
>> >
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
>
> --------------------------------------------
> Grant Ingersoll | @gsingers
> http://www.lucidworks.com
>
>
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Jan Høydahl / Cominvent
In reply to this post by Grant Ingersoll-2

> Main question:  Should we
> [] Lock down the Solr Wiki sooner rather than later and put all focus on adding to and improving the Ref Guide

+1

And put 301 redirects to cwiki for as many of the old pages as possible.

Can we have a new Confluence space where non-committers are allowed to share stuff? I hate the old wiki syntax :)

Reminds me that the Apace OpenOffice project had a similar discussion about non-programmer contributors. When part of Oracle they had separate teams for marketing, documentation etc but @ Apache it's all flat so they had to adapt and make people into committers even if they are only translating the documentation.

Jan
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Alexandre Rafalovitch
In reply to this post by Grant Ingersoll-2
On Sun, Apr 6, 2014 at 5:12 PM, Grant Ingersoll <[hidden email]> wrote:
> While I somewhat agree with both the points of Furkan and Alexandre, I am
> not sure which way you are leaning:

If somebody had time/money/permission, that's what I would do
1. Migrate wiki to an archive area in bulk and freeze - do not delete
2. Mark it as Google non-crawlable in robot.txt
3. Setup proper redirects for the well known old URLs (use Google
analytics, log analytics or common sense to figure it out)
4. Setup Log watch for URLs that used to go to the wiki. As particular
URLs that are hit, review and create stub pages, contact originating
pages to ask to point to new location
5. Do something about JavaDocs polluting Google Index. At minimum,
create /latest/ as a stable URL path and have it very Google visible.
Make the rest of the versions in archive, non-crawlable. There is a
lot more that can be done here, but probably not as part of this
cleanup (see my older post about it)
6. Fix general SEO about highlighting Solr's best new features (NRT,
Cloud, Schema/SchemaLess)
7. Setup proper analytics (is there any?), so we could at least tell
what people find and what they do not.
8. Decide what happens with non-commiters contributions (still not
clear to me). If tips and tricks is the main focus, then perhaps there
should be some dedicated space for it with voting or whatever. Or
delegate that to StackOverflow's communal wiki services, which gives
authentication, voting, gamification, etc. Or even create a separate
SEARCH group on SO with questions spanning all the different Lucene-
and non-Lucene-based offerings. I bet there will be a lot of common
questions on tokenization, etc.

The problem I guess is to figure out what the critical path is. Some
things cannot be done alone or they will hurt the community.  E.g.
freeze the wiki AND give no way to contribute - is not so good.

Regards,
    Alex.


Personal website: http://www.outerthoughts.com/
Current project: http://www.solr-start.com/ - Accelerating your Solr proficiency

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Shalin Shekhar Mangar
On Mon, Apr 7, 2014 at 9:58 AM, Alexandre Rafalovitch
<[hidden email]> wrote:
> On Sun, Apr 6, 2014 at 5:12 PM, Grant Ingersoll <[hidden email]> wrote:
>> While I somewhat agree with both the points of Furkan and Alexandre, I am
>> not sure which way you are leaning:
>
> If somebody had time/money/permission, that's what I would do
> 1. Migrate wiki to an archive area in bulk and freeze - do not delete

+1

> 2. Mark it as Google non-crawlable in robot.txt

Don't do that. Setting up a permanent redirect to new pages is enough.
Google and other bots soon figure out that the new pages are supposed
to be the definitive page and they stop showing old pages. By marking
them as non-crawlable, you will stop bots from accessing our old pages
and not even the permanent redirects will be read by them. This means
that the page rank for our new pages will have to be rebuilt over time
as more and more people link to them.

> 3. Setup proper redirects for the well known old URLs (use Google
> analytics, log analytics or common sense to figure it out)

We should make sure it is a HTTP 301 - permanent redirect instead of HTTP 302.

> 4. Setup Log watch for URLs that used to go to the wiki. As particular
> URLs that are hit, review and create stub pages, contact originating
> pages to ask to point to new location
> 5. Do something about JavaDocs polluting Google Index. At minimum,
> create /latest/ as a stable URL path and have it very Google visible.
> Make the rest of the versions in archive, non-crawlable. There is a
> lot more that can be done here, but probably not as part of this
> cleanup (see my older post about it)

I am not sure if that is a big problem for Solr. How many people look
at our javadocs? How many of us actually write them?

> 6. Fix general SEO about highlighting Solr's best new features (NRT,
> Cloud, Schema/SchemaLess)

+1

> 7. Setup proper analytics (is there any?), so we could at least tell
> what people find and what they do not.

I know this has come up before. I think there is a legal issue with
using free analytics tools such as Google Analytics etc. I'd love to
see that though.

> 8. Decide what happens with non-commiters contributions (still not
> clear to me). If tips and tricks is the main focus, then perhaps there
> should be some dedicated space for it with voting or whatever. Or
> delegate that to StackOverflow's communal wiki services, which gives
> authentication, voting, gamification, etc. Or even create a separate
> SEARCH group on SO with questions spanning all the different Lucene-
> and non-Lucene-based offerings. I bet there will be a lot of common
> questions on tokenization, etc.
>
> The problem I guess is to figure out what the critical path is. Some
> things cannot be done alone or they will hurt the community.  E.g.
> freeze the wiki AND give no way to contribute - is not so good.
>
> Regards,
>     Alex.
>
>
> Personal website: http://www.outerthoughts.com/
> Current project: http://www.solr-start.com/ - Accelerating your Solr proficiency
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>



--
Regards,
Shalin Shekhar Mangar.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Toke Eskildsen
On Mon, 2014-04-07 at 08:35 +0200, Shalin Shekhar Mangar wrote:

> On Mon, Apr 7, 2014 at 9:58 AM, Alexandre Rafalovitch
> <[hidden email]> wrote:
> > 5. Do something about JavaDocs polluting Google Index. At minimum,
> > create /latest/ as a stable URL path and have it very Google visible.
> > Make the rest of the versions in archive, non-crawlable. There is a
> > lot more that can be done here, but probably not as part of this
> > cleanup (see my older post about it)
>
> I am not sure if that is a big problem for Solr. How many people look
> at our javadocs? How many of us actually write them?

Non-existing JavaDocs is a problem in itself, but even with the current
state, I expect to be able to find the current JavaDocs (i.e. for the
latest stable release) through a generic search on the Internet.

If the result is a page with just the auto-generated stuff and no real
explanations, then I at least know that I can stop searching.

- Toke Eskildsen, State and University Library, Denmark



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Noble Paul നോബിള്‍  नोब्ळ्

How do we plan to redirect? If I reached a specific page in the wiki after searching in Google and now tog forward me to the home page of cwiki ?
Isn't it better to give links at the top of the page to relevant sections in cwiki (as much add possible)
I'm +1 for locking the old wiki down

On 7 Apr 2014 13:13, "Toke Eskildsen" <[hidden email]> wrote:
On Mon, 2014-04-07 at 08:35 +0200, Shalin Shekhar Mangar wrote:
> On Mon, Apr 7, 2014 at 9:58 AM, Alexandre Rafalovitch
> <[hidden email]> wrote:
> > 5. Do something about JavaDocs polluting Google Index. At minimum,
> > create /latest/ as a stable URL path and have it very Google visible.
> > Make the rest of the versions in archive, non-crawlable. There is a
> > lot more that can be done here, but probably not as part of this
> > cleanup (see my older post about it)
>
> I am not sure if that is a big problem for Solr. How many people look
> at our javadocs? How many of us actually write them?

Non-existing JavaDocs is a problem in itself, but even with the current
state, I expect to be able to find the current JavaDocs (i.e. for the
latest stable release) through a generic search on the Internet.

If the result is a page with just the auto-generated stuff and no real
explanations, then I at least know that I can stop searching.

- Toke Eskildsen, State and University Library, Denmark



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Alexandre Rafalovitch
In reply to this post by Shalin Shekhar Mangar
Follow-up in-line.

On Mon, Apr 7, 2014 at 1:35 PM, Shalin Shekhar Mangar
<[hidden email]> wrote:
> On Mon, Apr 7, 2014 at 9:58 AM, Alexandre Rafalovitch
> <[hidden email]> wrote:
>> On Sun, Apr 6, 2014 at 5:12 PM, Grant Ingersoll <[hidden email]> wrote:
>> 2. Mark it as Google non-crawlable in robot.txt
>
> Don't do that. Setting up a permanent redirect to new pages is enough.
I meant add the NEW archive location to the non-crawlable. So,
(desperate) people could still find it by manually browsing, but no
search will return those.

>> 5. Do something about JavaDocs polluting Google Index. At minimum,
>> create /latest/ as a stable URL path and have it very Google visible.
>> Make the rest of the versions in archive, non-crawlable. There is a
>> lot more that can be done here, but probably not as part of this
>> cleanup (see my older post about it)
>
> I am not sure if that is a big problem for Solr. How many people look
> at our javadocs? How many of us actually write them?
I would not have gotten this far without JavaDocs. A lot of
UpdateRequestProcessors have their settings described in JavaDoc only.
Plus, the only way to find about new classes is by crawling the
JavaDoc hierarchy (which also has issues). I think it is a real issue
for beginner=>intermediate upgrade.


>> 7. Setup proper analytics (is there any?), so we could at least tell
>> what people find and what they do not.
>
> I know this has come up before. I think there is a legal issue with
> using free analytics tools such as Google Analytics etc. I'd love to
> see that though.

http://piwik.org/ ? The web analytics is incredibly valuable. If there
is an issue with using it, it should be worked through. It allows to
make actionable decisions based on real usage.

Regards,
     Alex.
Personal website: http://www.outerthoughts.com/
Current project: http://www.solr-start.com/ - Accelerating your Solr proficiency

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Grant Ingersoll-2
In reply to this post by Shalin Shekhar Mangar

On Apr 6, 2014, at 11:35 PM, Shalin Shekhar Mangar <[hidden email]> wrote:

7. Setup proper analytics (is there any?), so we could at least tell
what people find and what they do not.

I know this has come up before. I think there is a legal issue with
using free analytics tools such as Google Analytics etc. I'd love to
see that though.

It's already in place.  Any committer who wants access can send me a gmail account and I can add you.

-Grant
Reply | Threaded
Open this post in threaded view
|

Re: Solr Ref Guide vs. Wiki

Alexandre Rafalovitch

Right. Now I just need to become a committer. :-)

Regards,
     Alex

On 07/04/2014 8:01 pm, "Grant Ingersoll" <[hidden email]> wrote:

On Apr 6, 2014, at 11:35 PM, Shalin Shekhar Mangar <[hidden email]> wrote:

7. Setup proper analytics (is there any?), so we could at least tell
what people find and what they do not.

I know this has come up before. I think there is a legal issue with
using free analytics tools such as Google Analytics etc. I'd love to
see that though.

It's already in place.  Any committer who wants access can send me a gmail account and I can add you.

-Grant