[
https://issues.apache.org/jira/browse/SOLR-11144?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16209702#comment-16209702
]
Cassandra Targett commented on SOLR-11144:
------------------------------------------
I've finally finished a rather thorough round of review & edits for these docs.
I changed a lot of stuff, so I created a branch {{jira/solr-11144}} and have
pushed that so you can pull the branch if you want - it's up to date with
master as of a few minutes ago.
I didn't keep a list of the stuff I changed as I went, so this list is from
memory - if you notice anything I changed to be incorrect, please let me know.
* I changed all of the usages of ⟹ to {{\=>}}. The character you used rendered
very small in both HTML and PDF. I could have left it as {{=>}} and asciidoctor
would have converted it to a nice icon that's larger than what you had used,
but this doesn't work in the PDF at all, so precommit doesn't allow it.
* A lot of your examples in the reference pages were in the form of {{"example
input" => "example output"}}, but the input/output sections should be
separately monospaced to avoid confusion about which is input and which is
output. I changed these so it would look like "{{example input}} => {{example
output}}" instead.
* I normalized a lot of uses of bold text, particularly in examples, and
changed a lot of capitalization of words to lower case.
* In {{analytics-reduction-functions.adoc}}, all of the examples were marked as
Labeled Lists (with the double colons at the end of the line), but unlike the
other pages of reference, there are no examples that follow. Since there was no
entry for the list, this broke the PDF. I removed all of these so they are just
plain examples on a single line for each reduction function.
* In {{analytics.adoc}}:
** I changed the presentation of many of the sections of parameters - we
generally do these as Labeled Lists, but you used nested unordered lists (i.e.,
bullet points) which were quite confusing. I _think_ I grokked the
relationships between all the parameters, but you should double-check those
because I had a hard time wrapping my head around it completely. As a related
note, parameters should also always be in monospace instead of bold - I think I
caught all of these, but may have missed one or two.
** I added some comments that we should address, particularly in the faceting &
grouping section. I could see this aspect of the component being used a lot,
and the parameters seem under-described to me.
** The section on Setup didn't cover adding the path to the .jar to the <lib>
directive in solrconfig.xml, so I added that. The Overview section was also
removed and replaced with it's sub-sections as main sections.
One thing I did not fix but needs to be fixed is a mismatch in some pages
between the page title and the page shortname - in order for PDF linking to
work properly, every {{page-shortname}} must match the title and must match the
filename (without the .adoc file extension), due to the way the PDF is built as
one massive file. If they don't match, the bookmark reference in the PDF won't
point to anything and users will jump halfway through a section (if the link
happens to work at all, sometimes it won't). This wasn't something you would
have known when you wrote this, but we need to fix it before we commit it. We
can either change the {{page-shortname}} & filenames on these pages or change
the page titles - which do you prefer? These are the pages with the mismatch:
* analytics-reduction-functions.adoc
* analytics-mapping-functions.adoc
* analytics-expression-sources.adoc
I think that's the bulk of what I changed but may have forgotten some major
things since I've been looking at this off & on for a few weeks between other
tasks - if you have any questions, please let me know.
> Analytics Component Documentation
> ---------------------------------
>
> Key: SOLR-11144
> URL: https://issues.apache.org/jira/browse/SOLR-11144
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Affects Versions: 7.1
> Reporter: Houston Putman
> Assignee: Cassandra Targett
> Priority: Critical
>
> Adding a Solr Reference Guide page for the Analytics Component.
--
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
