Shaping an initial Editor Guide

Summary

• Appetite: 2d
• Problem: need instructions to give people about how to set up their repo so it works with DataHub cloud
• Solution: template repo plus instructions and some reference material

Situation

Context: people are using this guide when they want to try the product out

Let's look at the steps in the funnel to using our app:

• Discovery: they hear about, come across our website etc
• Choose to try: they read site etc and can see it solves a pain, or maybe even just curious
• Try it: Sign up etc. does it work? does it look like it could really address my need (even if not immediately with this try-out) 👈👈 this is where we are focused with the instructions and journey
• Return: … keep trying … and it does address a need
• Pay/Continue subscription

Context: nature of the app

• runs off-GitHub - users bring their data/content stored in GitHub repositories.
• There is no built in markdown editor or data upload option.
• Users need therefore to create there datasets and data stories themselves in github using markdown and csv
• We have requirements on frontmatter for us to display their datasets
• We have requirements on type of data they can provide e.g. only CSV atm (?)
• We support "data rich documents" with a bunch of markdown plus features users may not be aware of e.g. table rendering, graph rendering, plus all the flowershow goodness

Problem

• People may like a walkthrough to get started so that they have a sense of the app and something that works straight away
  • => a combination of instructions/tutorial with a template repo with good UX
• If they just dive in with a random github repo it may not work so nicely or may break
  • => we need to guide them to use the features
  • => we need to avoid (or quickly solve) breakdowns they have …
  • => starting from basic step by step instructions with something that works may avoid or ameliorate both of these

Why the app may not work so well

Users may know how to format their content and data so that it will work (or work well) on DataHub Cloud

• How to have a table display
• How to show an image
• How to have a graph
• How to list all their data files so they are shown

In addition, user may not: (NB: below we relegate these to no goes)

• Know to use github very well
• Know what markdown is or how to use it

OLD (note how this is a solution masquerading as a problem: a guide is already some part of a solution)

Appetite

Up to 2d

Solution

Hypothesis: Create some simple instructions with a template that the user can try out.

Bonus:

• 1 or 2 examples
• A more detailed tutorial
• Reference docs on "markdown plus" features
• Refereces docs on table and visualization features

Notes

• Will create tutorial in a repo and publish using datahub cloud itself

Sketch of instructions

Intro text:

Assumed knowledge

• We assume you have an account on github
• We assume you have a (very rough) sense of github
  • Actually: even if you don't you can follow the step and it will work. But once you want to go further.

Step by step

• TODO: decide whether our instructions focus on a datws
  • OR: give users a choice?? (I don't like choices)
  • MAYBE: explain we are going with publishing a dataset but you can easily convert to a simple data story if you want …
• Go to this template repo
• Click "use this as a template"
  • 👉📷 (outcome image) You'll have a nice new repo like this
• Now go to DataHub.io and sign up.
  • 🚩 you may need to wait for your waitlist invite to come through 😉
• Walk through the steps to create a new project
  • Use the github repo you created in the last step
• The result should be something like this:
  • 👉📷 show picture of standard page …
  • Not very exciting yet 😉 well let's see …
• Now we are going to add X, Y e.g. a graph
  • Let's go modify our github repo we created earlier
  • We'll add a table
• Let's add a second data file …??

Inventory of existing tutorials

• PortalJS tutorial https://portaljs.org/docs. This is most thorough tutorial. Covers building an entire catalog. Focused on PortalJS.
• 2 tutorials written by Demenech for DataHub v3-v1 in April 2023
  • https://github.com/datahubio/tutorial
  • https://github.com/datahubio/tutorial-frictionless-project
• Data Rich tutorial for DataHub v3-v2 in Nov 2023
  • https://datarich-demo.datahub.io/ ❓ not working for some reason
  • https://demo.datahub.io/@datahubio/tutorial
• Flowershow tutorials https://flowershow.app/docs ✅2024-02-16 ❌ none of these are immediately relevant
  • How to (self) publish your markdown files with Obsidian Flowershow plugin https://flowershow.app/docs/publish-howto
  • Blog tutorial https://flowershow.app/docs/blog-tutorial
  • Customize theme https://flowershow.app/docs/custom-theme
  • Jumpstart Nextjs site with Flowershow https://flowershow.app/blog/2023-02-16-nextjs-tutorial
• Markdown tutorials
  • https://www.datopian.com/playbook/markdown

Principles

• KISS: i.e. do the minimum for now.
• Examples and templates are the most useful
• Reference docs can come later

Rough plan of work

• Create the template repo
• Create the instructions
• Publish instructions using datahub cloud
• Publish template repo live with datahub cloud …

Analysis

Some combintation of the following will address problem 1 + 2:

• A tutorial walking users creating and publishing a dataset from start to finish
• Template repo that people can use as a template or copy and paste
• Example repos demonstrating features

Rabbit holes / Risks

• App changes substantially making the instructions obsolete Can address changes quite quickly plus assume app won't change right now

No Goes

• Explaining how to use github: we assume users know how to use github.
• Explaing about markdown: we assume users know about markdown
• Detailed Instructions explaining how to use DataHub Cloud to publish a GitHub repo once it exists (beyond what we have in the guide for creating the repo). We imagine the UX of our app is good enough and clear enough that a guide is not needed. To extent we have stuff like this it is probably marketing copy on the front page.

Appendix

Possible future work

Iteration 2: more tutorials and other resources

Iteration 2: make it look professional

Appendix: Daniela thinking out loud 2024-02-16

• What prerequisites does a user need to have in order to publish their dataset/story with Datahub Cloud? Eg. a user need to have the data in X and Y format, they need to have a data package, Z metadata in the frontmatter TODO: what's your answer?
• Everything else is app-intuitive. We do not need a guide for what's available in the UI
• Do we need instructions for after a user publishes their dataset? If they want to customize, we assume they know how to do it.
  • However, if they want to create a DATASET page for instance, there should be a special frontmatter that has to be added. What fields are supported currently etc.
    • Is this a STANDARD amongst our target audience, eg. would our users know about https://specs.frictionlessdata.io/data-package/#language
    • Can we solve this by creating an example repo?
  • Can I customize the table format, if eg. i am a developer and I know how to do it in css/html?

Appendix: FAQS

• [Daniela] People are coming with pre-existing repos and they may not want to use a template repo.
  • [Rufus] People only come to tutorial once they are clear that they want to use the product
  • [Rufus] People have to discover or hear about the product before deciding to use it. They need to believe it in some way so that they go investigate it. PROVIDED BY: landing page

Terminology: let's use the word "instructions" rather than overloading tutorial.