lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Cassandra Targett (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (SOLR-11144) Analytics Component Documentation
Date Wed, 18 Oct 2017 17:20:00 GMT

    [ 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-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message