Guided Tours: add a tutorial to the documentation #10035

merged 4 commits into from Jan 10, 2017


None yet

5 participants

lsinger commented Dec 14, 2016 edited

This PR adds a tutorial to the Guided Tours documentation that walks the reader through building a simple tour.

To test: follow the tutorial and ...

  • ... see whether the copy is comprehensible enough
  • ... check whether important things are missing
  • ... see whether the resulting tour works
@lsinger lsinger added this to the GuidedTours M6: Documentation milestone Dec 14, 2016
@lsinger lsinger self-assigned this Dec 14, 2016
@lsinger lsinger closed this Dec 14, 2016
@lsinger lsinger reopened this Dec 14, 2016

As I said before, I think the outline is good. I've added a few notes. Do ping whenever you want another look!

+4. Show the user how to exit the preview and wait for them to do it.
+5. Finish the tour.
+We could have included a step — or even multiple steps — to explain the different device sizes, but it's advisable to start off with tours that are as short as possible to see how they perform. We can always come back and add additional steps.
mcsf Jan 4, 2017 Member

Somewhere in this section, whether before or after the list, I'd make it clear that we're intentionally adding a lot of point for the sake of illustration, and that a better UX is generally one that minimizes interaction redundancy. What I mean by that is that, with most tours, developers should prefer an initial step that is ready for action: instead of asking for the user's time, directly point to the element(s) of interest; instead of adding a useless Next element, prefer a Continue step ready to react to the user's trigger (which is a confirmation of their interest to take the tour).

+- decide for tour steps: what do you want to achieve?
+- make <Tour>
+- add <Steps> with text and default positioning
+- add an abtest and add the abtest selector as the last when condition
mcsf Jan 4, 2017 Member

Yup. In the final copy, I'd super quickly explain why this is important.

+abtest as last selector in trigger condition
+we should keep track of the tour
+there are tracks events for staring, quitting, and finishing tours
mcsf Jan 4, 2017 Member

Since Tracks is a private resource, I'd mention it as lightly as possible. Those with access to it will know how to make use of it. Maybe worth adding to the Field Guide?

+animation delay:
mcsf Jan 4, 2017 Member

That one is an interesting case, and worth presenting, but perhaps with a disclaimer? Not sure, but something like: "Use sparingly, or don't. Before you do, ask yourself whether what you are attempting to solve can't be solved with better selectors for when."

+how to do the calls and when to add them (when copy has been reworked, also maybe after `en` a/b test)
+formatting with {{strong}} etc., adding GridIcons, ...
mcsf Jan 4, 2017 Member

IMO all of the Translation section can be distilled down to a very brief sentence (e.g. "regular Calypso guidelines apply: minimize string churn*, use proper formatting and component interpolation (cf. i18n-calypso) when needed")

*: no idea if "string churn" is a term, but I mean avoiding generating throwaway strings


Tutorial reads very well - great job so far! Some ideas that you probably thought about, but aren't outlined at the moment:

  • writing tours - use a combination of both designer and developer that have knowledge about some particular area in Calypso
  • use Editorial as a resource to make a good and understandable instructions
  • add a link to launch the example tour. I thought you will make just a theoretical tutorial, but also having the "real thing" done and usable is even better!
@lsinger lsinger requested a review from mcsf Jan 6, 2017

Nice work, this has come a long way!

I raised a couple of remaining questions and also just pushed a commit with loose changes.

+ path="/stats"
+ when={ and(
+ isNewUser,
+ isEnabled( 'guided-tours/tutorial-site-preview' )
mcsf Jan 9, 2017 Member

Maybe the feature flag check should be first, as a general principle, as a short-circuit?

@@ -43,6 +43,7 @@
"dev/test-helper": true,
"guided-tours": true,
"guided-tours/main": true,
+ "guided-tours/tutorial-site-preview": true,
mcsf Jan 9, 2017 Member

I'm not sure we should merge the PR with this flag enabled. Even though it's only for development, it is going to pop up perhaps unexpectedly for people who are not aware that it is just a tutorial, adding noise/distraction or generating the fear that an unnecessary tour is active. The tour will still be accessible to people interested in Guided Tours (and trying out the tutorial tour) via one of two ways: query argument and manually enabling the feature flag.

If you think about it, even right now developers will likely resort to the query argument method, since by default they will be using an account that doesn't match the isNewUser criterion. So setting this flag to false seems valuable to me (it shows that it is good to use feature flags, even though ours is switched off).

lsinger commented Jan 9, 2017

@mcsf thanks, all very good points. Addressed!

@@ -29,9 +29,10 @@ export default class Quit extends Component {
render() {
- const { children, primary } = this.props;
+ const { children, primary, subtle } = this.props;
mcsf Jan 9, 2017 Member

Oh, I forgot: add subtle to propTypes

mcsf approved these changes Jan 9, 2017 View changes

Looks great! Left a couple of notes.

lsinger commented Jan 9, 2017

Thanks! Fixed.

@lsinger lsinger merged commit f44a6f8 into master Jan 10, 2017

1 check passed

ci/circleci Your tests passed on CircleCI!
@lsinger lsinger deleted the update/guided-tours-docs-tutorial branch Jan 10, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment