search

elastic / stack-docs

Elastic Stack Documentation
Other
95 stars 252 forks source link

Upgrade Path Builder #29

Closed debadair closed 6 years ago

debadair commented 7 years ago

This is still very much a WIP, but time is getting very short so opening this issue to get more eyeballs on it.

Looking for any and all feedback, but the most important thing is making sure that the various paths are fleshed out appropriately. That goes beyond making sure there aren't any paths that throw errors, the actual content & recommendations have to be accurate. And, of course, it needs to look decent -- @cjcenizal gets the cred for the styling, any bad line breaks, weirdo spacing, etc. are on me, along with the content issues.

You can try out a live preview at: https://upgrade-adventure.firebaseapp.com/find_path.html

This is built using Twine--not a great longterm solution, but there wasn't enough time to roll our own. It uses the Sugarcube 2 story format. You can load the attached find_path.txt file into the online version of Twine to see a visualization of the paths. Right now, that looks like this:

image

I've also attached the "proofing" version that contains just the content source. (If you import find_path.txt into Twine, you can also view the proofing version in the app.)

find_path.txt find_path_source.txt

cjcenizal commented 7 years ago

On my side, I've integrated the builder with elastic.co locally by using @sylvie777's iframe-embedding technique:

image

I tried to integrate the source directly, but Twine creates some truly shudder-inducing code which doesn't play very well with ContentStack and results in a 500 error when you try to load the page. I couldn't figure out why.

In the long-term, I think we'll need to hand-roll a simple in-house system for this tool. Requirements would be:

  1. Allow the content-creator to easily define the branches in a tree like the one above.
  2. The content-creator should have complete control over the form UI of each node in the tree.
  3. As the user navigates to each node in the tree, render the form UI defined by the content-creator.
  4. As the user enters input into each form, store this form data.
  5. The content-creator should have access to a getNextNodeId(formData) hook. This hook is called when the user clicks the "Next" button. The formData object contains all of the user's input. The content-creator can write conditions to evaluate against this form data and return the id of the next node to be shown.
inqueue commented 7 years ago

Nice work @debadair! I realize this is very much WIP and I apologize if this is already on your radar. It looks like there is a missing line break after group headings on the 6.0 upgrade checklist.

screen shot 2017-11-08 at 11 24 08 am

debadair commented 7 years ago

No need to apologize...I have a list, this anomaly wasn’t on it. :-)

liztauscher commented 7 years ago

@debadair Love the way this looks!

Text cuts off and there is no scroll bar, so I can't progress forward or read all of the text To Replicate: "Let's Go, Select version=5.6, EC=yes, Products=Logstash & Kibana.

screen shot 2017-11-08 at 9 59 26 pm

It happens in a few places -- there is also some odd spacing.

Sorry for the noise if this is a known bug!

ppf2 commented 7 years ago

I know this is still a work in progress, I played around with it a bit. I probably haven't hit all the paths yet, here are the things I came across so far:

Btw, I love that we have this app to help demystify all the different paths 🎆 🍾 ❤️ :

So somehow the not using Cloud path got mixed up with the Cloud part further down the flow

This is before our check for TLS. Maybe we can delay showing this statement until after the TLS check?

Excited to see this tool!

debadair commented 7 years ago

I've checked in the source: https://github.com/elastic/stack-docs/blob/master/docs/60_upgrade_guide.html

It's now staged at: https://stag-www.elastic.co/products/upgrade_guide

My list of outstanding items is shrinking:

debadair commented 6 years ago

Shipped.