[
https://issues.apache.org/jira/browse/SOLR-11766?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16341225#comment-16341225
]
Cassandra Targett commented on SOLR-11766:
------------------------------------------
An interesting idea, Joel, and I totally understand why you're going that way.
A few counter-points, or maybe just additional things to consider.
bq. Streaming Expressions tend to hold up the release of the main reference
guide.
At the risk of sounding flippant or disrespectful, there's a really easy way to
solve that: do your doc updates at the same time you add a new expression. The
"wait until the RC has been cut then start doc updates" approach is the only
thing holding up merging the Ref Guide release with the main artifact release
(and I'll add it is not in the slightest pleasant for me, the one who is nearly
always the RM). Sure, one way around it is to release separately, but a more
direct way is to just do them at the same time.
bq, If they we're in there own guide they could release later
At some point we need to split up the Ref Guide - it's massive (1,200 pages in
PDF) and grows more untenable with each release - but there are a number of
factors to consider:
# Unless all the separate PDFs are released at the same time, they require VOTE
threads for each release.
# Even if we changed to consider the HTML as the official format, we would
still need a VOTE for each release. That means instead of going to a single
release process for Lucene/Solr + Ref Guide, we'd still have at least 2 and
possibly 3 or more release processes. The current Ref Guide release takes ~1
week of my time full-time every time - it's not a hit the button and walk away
kind of thing if you want it done with any quality. IOW, since I'm the one
doing it 99.9% of the time, I don't have time for more than a single release
cycle no matter how many PDFs are generated.
# I've gone through the exercise in the past of splitting a single massive PDF
into multiple separate PDFs, and one of the most hellish aspects of it was
trying to handle links to sections that end up in different PDF files (like, I
want to link to details about fields while describing the types of fields
expressions would support). You can't. And since we have both an HTML and PDF
format, links that work for the HTML version won't work for the PDF, so there
would be additional issues to straighten out to make that work properly.
bq. Right now the Streaming Expression documentation is being wedged into an
existing format
I infer from this comment that you have ideas but think they may not possible.
Beyond splitting the pages into sub-sections, I don't recall other ideas you've
shared that were rejected due to format limitations...but perhaps I'm
forgetting something?
We have two real limitations, IMO: 1) the fact that the official release
artifact is the PDF, which is very book-like and does not support many
interactive features we may want to include; and 2) our imaginations and skills.
Regarding the first limitation, some users want a PDF. We would still be asked
to create one even if it was not the "official" format that we vote on. I don't
see it going away entirely, so that limitation will always be around.
For the second - The HTML version is incredibly flexible. We can lay out those
pages however we want. We can make the Streaming Expression pages look totally
different than other pages by providing a layout template for them and telling
each page to use it. We can add javascript this or that to do all kinds of fun
things. But we need ideas first (I've shared those I've had), and then possibly
someone with deeper skills than mine to make it happen.
If we do come up with some great ideas, we may need to do a couple of things to
make the same info appear properly in the PDF, but nearly anything you can
think of for online information design is within our grasp if we have a) the
ideas and the ability to implement them, and b) the willingness to maintain it
release-to-release as new expressions are added. It's not that hard to make
things work properly in the PDF, you just need to be cognizant of the need for
it.
At the very least, I think we should move Streaming Expressions out of the
"Searching" section and make it a top-level section - the scope of what it can
do is way beyond "Searching" now and it deserves it - I'll do that in the patch
I'm working on with the other changes I've been making. But before we go ahead
and make it a standalone Guide on its own, I'd like to hear your point of view
on the other issues I've raised here.
> Ref Guide: redesign Streaming Expression reference pages
> --------------------------------------------------------
>
> Key: SOLR-11766
> URL: https://issues.apache.org/jira/browse/SOLR-11766
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation, streaming expressions
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
> Priority: Major
> Attachments: Stream-collapsed-panels.png, StreamQuickRef-sample.png,
> Streaming-expanded-panel.png
>
>
> There are a very large number of streaming expressions and they need some
> special info design to be more easily accessible. The current way we're
> presenting them doesn't really work. This issue is to track ideas and POC
> patches for possible approaches.
> A couple of ideas I have, which may or may not all work together:
> # Provide a way to filter the list of commands by expression type (would need
> to figure out the types)
> # Present the available expressions in smaller sections, similar in UX
> concept to https://redis.io/commands. On that page, I can see 9-12 commands
> above "the fold" on my laptop screen, as compared to today when I can see
> only 1 expression at a time & each expression probably takes more space than
> necessary. This idea would require figuring out where people go when they
> click a command to get more information.
> ## One solution for where people go is to put all the commands back in one
> massive page, but this isn't really ideal
> ## Another solution would be to have an individual .adoc file for each
> expression and present them all individually.
> # Some of the Bootstrap.js options may help - collapsing panels or tabs, if
> properly designed, may make it easier to see an overview of available
> expressions and get more information if interested.
> I'll post more ideas as I come up with them.
> These ideas focus on the HTML layout of expressions - ideally we come up with
> a solution for PDF that's better also, but we are much more limited in what
> we can do there.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
