While some of this could hypothetically be confusing, I don't think it will be in reality. Surprising, yes, but I don't think in a bad way.
I'm against cluttering the examples with all of the parameters... but prepending "..." to show that some parameters have been omitted seems OK. I'll do it now. -Yonik http://www.lucidimagination.com On Mon, Oct 26, 2009 at 11:58 AM, Chris Hostetter <hossman_luc...@fucit.org> wrote: > > : These are realy URL fragments... none of the other examples show the > : indent=on or the rest of the URL either, and when we get down to > > indent=on doesn't really affect the structure of the response docs > (especially since people following the tutorial are likely to be using a > browser that pretty prints the XML) ... if you set indent aside, all > of the demo links in the previous versions of the tutorial were either... > > 1) full URLs (starting with http://...) > 2) SolrQuerySyntax (w/o any url escaping or metacharacters) when the > text arround them made it clear they were query sytnax examples not > URL fragments > 3) full /select URL query parts (ie: everything after the "?") > > ...the new sections you've added (highlighting & faceting) *look* like > they are type#3, expcet that they leave out params that change the > functionality. If the link text left out *all* params except the > ones being showcased and contained elipses or soemthing to indicate that > they were partial... > > THIS: "...&hl=true&hl.fl=name,features" > INSTEAD OF: "q=video card&fl=name,id&hl=true&hl.fl=name,features" > > ...then it would probably be less confusing when other params besides the > ones in the link text were acctually used in the link href (and would draw > attention to the fact that we are building off of other params already > seen) > > : faceting, the "fl" is also hidden. Showing all of the parameters > > i missed that you added that fl there as well (the json formating made it > less obvious when looking at the result page) but it's just another > example of my point. > > Ultimately my concern is just that we try to be consistent with our > exmaple URLs, > and your point about indent illustrates that we weren't really that good > about it before, but let's try to be at least as good as 1.3 or better. > > So the question is: should the links in the tutorial focus on being > completely transparent (ie: show everything) or should they focus just on > illustrating the new params we're introducing in that section? and if > the later, what's the best way to make it clear that's what we're doing? > > : As you point out, the wt=json parameter was explicitly presented > : earlier, so it seems fair game for not calling it out explicitly. > > But it's presented more as an asside that in that one link we're using > JSON ... for the entire "Sorting" section that follows we don't use it > again, so it's kind of confusing when the results start popuing up in json > form in the highlighting section. (if we had some verbage when we > introduce "wt=json" about the remainder of the links using that format for > readability, and then we add it to all of the href's in the Sorting > section itwould be a lot less suprising. > > : JSON prevents highlighter markup from being escaped... didn't want > : anyone seeing <em> > : The other benefit is vertical size - the XML format often consumed > > Like i said: i'm totally fine with using the JSON format in the tutorial, > i just want to make it more transparent. > > > > > -Hoss > >
