[
https://issues.apache.org/jira/browse/SOLR-11032?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16219957#comment-16219957
]
Jason Gerlowski edited comment on SOLR-11032 at 10/26/17 4:30 AM:
------------------------------------------------------------------
bq. some choices in RefGuideSolrJExampleTest don't make a lot of sense to me
Those criticisms are pretty fair. Most of my attention was to the
documentation itself, and I let the test file suffer as a result. I've
addressed many of your points in the attached patch.
The only exception to this was your feedback regarding unnecessary {{println}}
statements, which I agree with but opted for a different approach on. I had
initially put these prints into the doc snippets as a stand-in for saying:
"You've got the object X you were after, now use it, however you want". But on
reflection, those print-statements aren't really conveying any useful
information to the reader. (They don't even show off any of the APIs of the
SolrJ value types, since it's literally just an implicit toString call!).
So instead of hiding our assertions behind mock print statements as Hoss
suggested, I just removed them altogether. Or rather, I replaced them with the
assertions you mentioned were previously lacking. If you'd still prefer the
mock-print approach, I'm happy to take that approach too.
bq. [copying Java files to the src tree] ... seems like a recipe for
disaster/confusion
I hadn't considered that pitfall, and I agree it's worse than the
"live-preview" disease it cures. I've modified the build-init target to copy
to build.content.dir as you suggested.
bq. those suggested changes/improvements shouldn't hold up the basic idea of
improving the solrj documentation
I tried to get a fixed patch out for the things you guys mentioned; I know
Cassandra's trying to do a ref-guide release this week, I don't want to get in
the way of that. If this latest patch still isn't quite ready for primetime,
just wanted to remind you that the first patch on this JIRA has doc
updates-only, in anticipation of this sort of scenario. We could always go
with that if you think the doc-content is in a good place, but have
reservations about the other moving pieces.
Thanks again for your time guys.
was (Author: gerlowskija):
bq. some choices in RefGuideSolrJExampleTest don't make a lot of sense to me
Those criticisms are pretty fair. Most of my attention was to the
documentation itself, and I let the test file suffer as a result. I've
addressed many of your points in the attached patch.
The only exception to this was your feedback regarding unnecessary {{println}}
statements, which I agree with but opted for a different approach on. I had
initially put these prints into the doc snippets as a stand-in for saying:
"You've got the object X you were after, now use it, however you want". But on
reflection, those print-statements aren't really conveying any useful
information to the reader. (They don't even show off any of the APIs of the
SolrJ value types, since it's literally just an implicit toString call!).
So instead of hiding our assertions behind mock print statements as Hoss
suggested, I just removed them altogether. Or rather, I replaced them with the
assertions you mentioned were previously lacking. If you'd still prefer the
mock-print approach, I'm happy to take that approach too.
bq. [copying Java files to the src tree] ... seems like a recipe for
disaster/confusion
I hadn't considered that pitfall, and I agree it's worse than the
"live-preview" disease it cures. I've modified the build-init target to copy
to ${build.content.dir} as you suggested.
bq. those suggested changes/improvements shouldn't hold up the basic idea of
improving the solrj documentation
I tried to get a fixed patch out for the things you guys mentioned; I know
Cassandra's trying to do a ref-guide release this week, I don't want to get in
the way of that. If this latest patch still isn't quite ready for primetime,
just wanted to remind you that the first patch on this JIRA has doc
updates-only, in anticipation of this sort of scenario. We could always go
with that if you think the doc-content is in a good place, but have
reservations about the other moving pieces.
Thanks again for your time guys.
> Update solrj tutorial
> ---------------------
>
> Key: SOLR-11032
> URL: https://issues.apache.org/jira/browse/SOLR-11032
> Project: Solr
> Issue Type: Task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation, SolrJ, website
> Reporter: Karl Richter
> Attachments: SOLR-11032.patch, SOLR-11032.patch, SOLR-11032.patch,
> SOLR-11032.patch
>
>
> The [solrj tutorial](https://wiki.apache.org/solr/Solrj) has the following
> issues:
> * It refers to 1.4.0 whereas the current release is 6.x, some classes are
> deprecated or no longer exist.
> * Document-object-binding is a crucial feature [which should be working in
> the meantime](https://issues.apache.org/jira/browse/SOLR-1945) and thus
> should be covered in the tutorial.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
