Chris M. Hostetter created SOLR-14383:
-----------------------------------------
Summary: Fix indexing-nested-documents.adoc XML/JSON examples to
be accurate, consistent, and clear
Key: SOLR-14383
URL: https://issues.apache.org/jira/browse/SOLR-14383
Project: Solr
Issue Type: Sub-task
Reporter: Chris M. Hostetter
As reported on solr-user@lucene by Peter Pimley...
{noformat}
The page "Indexing Nested Documents" has an XML example showing two
different ways of adding nested documents:
https://lucene.apache.org/solr/guide/8_5/indexing-nested-documents.html#xml-examples
The text says:
"It illustrates two styles of adding child documents: the first is
associated via a field "comment" (preferred), and the second is done
in the classic way now referred to as an "anonymous" or "unlabelled"
child document."
However in the XML directly below there is no field named "comment".
There is one named "content" and another named "comments" (plural),
but no field named "comment". In fact, looking at the Json example
immediately below, I wonder if the XML element currently named
"content" should be named "comments", and what is currently marked
"comments" should be "content"?
Secondly, in the Json example it says:
"The labelled relationship here is one child document but could have
been wrapped in array brackets."
However in the actual Json, the parent document (ID=1) with a labelled
relationship has two child documents (IDs 2 and 3), and they are
already in array brackets.
{noformat}
* The 2 examples (XML and JSON) should be updated to contains *structurally*
identical content, (ie: same number of documents, with same field values, and
same hierarchical relationships) to focus on demonstrating the syntax
differences (ie: things like the special {{\_childDocuments\_}} key in json)
* The paragraphs describing the examples should be updated to:
** refer to the correct field names -- since both "comments" and "contents"
fields exist in the examples, it's impossible for novice users to even
udnerstand where th "typo" might be in the descriptions (I'm pretty
knowledgeable about Solr and even i'm second guessing myself as to what the
intent in these paragraphs are)
** refer to documents by {{"id"}} value, not just descriptors like "first" and
"second"
* it might be worth considering rewriting this section to use "callouts":
https://asciidoctor.org/docs/user-manual/#callouts -- similar to how we use
them in other sections like this:
https://lucene.apache.org/solr/guide/8_5/uploading-data-with-index-handlers.html#sending-json-update-commands
--
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
