[
https://issues.apache.org/jira/browse/SOLR-14383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17166892#comment-17166892
]
David Smiley commented on SOLR-14383:
-------------------------------------
Hoss: please use PRs, which are much easier to peer review. I've been dragging
my feet, not looking forward to reading asciidoc diffs. Kudos to Jan on
pointing out GitHub's "rich diff" feature!
* I really appreciate the conversion of plain JSON input docs to a real curl
equivalent that I could use right away.
* The bullet advising the ID to be a composite ID for all docs in the block
really seems like it should be a TIP.
* Typo: thir -> their
* Typo: garuntee -> guarantee (multiple)
* The example about office supplies uses a child doc label of "docs", seen in
sending the data to Solr and in retrieval. I find the use of this word
confusing because it's a common word in Solr, so I suspect others might as
well. Perhaps "documentation" or "files" might be alternatives? "files" is
nice and short.
* In a section showing the child doc transformer, it used to have a link to
further details at
{{transforming-result-documents.adoc#child-childdoctransformerfactory}} but you
changed it to {{other-parsers.adoc#block-join-children-query-parser}}. That
doesn't make sense to me.
RE the nocommits relating to parent/child query parsers, perhaps [~mkhl] can
help with that. In my work with @moshebla on nested documents, we didn't touch
them. Ideally our project scope would have gone further and upgraded them too,
like we did for the child doc transformer. Alas; it was a partially
implemented overhaul.
> 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
> Assignee: Chris M. Hostetter
> Priority: Major
> Attachments: SOLR-14383.patch, SOLR-14383.patch, SOLR-14383.patch,
> SOLR-14383.patch
>
>
> 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
