[jira] [Commented] (SOLR-13042) Miscellaneous JSON Facet API docs improvements

["Jason Gerlowski (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-13042?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16710524#comment-16710524 ] 

Jason Gerlowski commented on SOLR-13042:
----------------------------------------

Though I only had small changes in mind initially, as I looked at these pages I think they could use a bit of a larger overhaul.  I think there's a good few things that could be improved.

Some of these are more general:
* add quotes to JSON snippets so that examples can be pasted into other editors or shared in other contexts without causing syntax highlighters to flare up.
* Change comments in existing JSON snippets to "callouts", so that they aren't included when the snippets get copy/pasted.
* Add corresponding SolrJ snippets for facet/query examples where possible and not already present


Some are specific to individual pages and tend to be a bit more structural:

*Json-Request-API Page*
* remove the "Error Detection" section, or move it somewhere else where it fits better
* move "Debugging" section out from under "Smart Merging of Multiple JSON Parameters", since it applies just as much to "Param Substitution" and "Passing Params"
* since we already have a descendant page for the querying syntax, would it make sense to move the JSON faceting page so it is also a descendant of "Json Request API"? 

*Json-Query-DSL Page*
* give it a little more explanation on why you would tag a query

*Json-Facet-API Page*
* removed the "design goals "section, as the doesn't seem appropriate for a rest guide
* reverse the metrics example in the bucket in example to Match the order they are introduced in
* get rid of the "making a faceting request" section and update all examples to have the appropriate curl header.
* Move the "Noggit"/"Json extensions" section over to the JSON top-level page since it applies to querying as well as faceting
* move terms, heatmap, range, etc under a "Types of Facets" top level section
* there's probably enough uses and examples of changing facet domains for it to be its own page.  Would that work?
* Remove the "references" section that has the links to Yonik's personal site.  I'm not sure where the ref-guide comes down on external links to blogs, etc. in general.  I'm not against it.  But here I dislike it because those links are already out of date in slight ways and that will only get worse as JSON faceting develops further.

> Miscellaneous JSON Facet API docs improvements
> ----------------------------------------------
>
>                 Key: SOLR-13042
>                 URL: https://issues.apache.org/jira/browse/SOLR-13042
>             Project: Solr
>          Issue Type: Bug
>      Security Level: Public(Default Security Level. Issues are Public) 
>          Components: documentation
>    Affects Versions: 7.5, master (8.0)
>            Reporter: Jason Gerlowski
>            Assignee: Jason Gerlowski
>            Priority: Minor
>
> While working on SOLR-12965 I noticed a few minor issues with the JSON faceting ref-guide pages.  Nothing serious, just a few annoyances.  Tweaks include:
> * missing/insufficient description of some params for Heatmap facets
> * Weird formatting on "Domain Filters" example
> * missing "fields"/"fl" in the "Parameters Mapping" table
> Figured I'd just create a JIRA and fix these before I forgot about them



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org