Feedback: On-boarding needs to be much better

Community
#1

I’m really excited about Blockstack and its objectives, it also seems to fill a need for the app I’m developing (managing user authentication and providing user-controlled storage). However, the actual on-boarding experience is horrific. If I’m struggling with it, so would my users and that’s a concern.

First, there’s too much ambiguous terminology being used. Figuring out what blockstack is and does is a task. Then you have to figure out how it works in practice and things get more confusing still. Is Blockstack browser necessary to use the technology? What is it, anyway? A browser like Chrome, Brave, Firefox? When you actually install it, it’s not clear what is being installed. It’s not obvious that it works with an existing Chrome browser, but isn’t an actual browser itself. I have multiple browsers installed, so I’m not sure it works across each or what it depends on. Will things work if I try to log in from any browser I use? None of this is clear from the outset.

I had created a blockstack id some time ago, which involves storing a string of words (the secret key). Fine, not a typical registration flow, but I’m thinking this will be something you use to retrieve access if you forget something about your account. Then I tried to log in at a later date and select the ‘log in with existing ID option’, expecting an ID + password combination. But instead it asked me for the secret key. Why? The screen isn’t telling me why. Once I plug that in, it wants to know my email and then it’s requesting I setup a password. Why? I have the password and ID at the ready. I haven’t done anything since I first created the ID. Why am I being asked to set a new password? Just more confusion.

So then I go along and set the password again. Am I good to go? Let’s try entering into an app. I click login with Blockstack and I get a window asking me to open the link with Office? What the actual? Reading the forum it seems like this issue was first reported a year ago. Okay, no fix shown but apparently you can click the office option and it will work regardless. But when I do, it just returns me to the same darn login screen. Clicking sign in with existing ID takes me through the same screens I went through earlier. Instead of smoothly logging in with my ID and password, it tries to send me back through entering the secret key and defining a password. I want to badly give up at this point. This shouldn’t be this hard.

Then there’s the blend of terminology used in the project. My first thought was, what the hell is app mining? Is it like bitcoin mining? Is whatever I’m going to install going to eat up computer processing time (which sounds awful)? It’s a pain trying to figure out that app mining is not remotely the same as bitcoin mining. I really think this was a poor choice of nomenclature and introduces more confusion and a bigger investment in time to just grapple with what we’re dealing with. This lack of simplicity and clarity is lacking elsewhere as well. If I’m struggling with it as an app developer, people who are just general users of apps are certainly not going to have it easy.

Lastly, since many app developers who are creating offline-first experiences will be using Electron, it was disappointing not to see a clear guide to getting set up with Electron and Blockstack. Researching this has left me even more confused.

tl;dr Please improve the on-boarding experience for both end-users and app developers by clearing away ambiguity, improving the messaging and making an easier path to adoption possible.

8 Likes
#2

Genuinely, thank you for this feedback. We will definitely have more people getting back to you.

1 Like
#3

@PeterKnight We are absolutely trying to improve our workflow so this kind of information is invaluable.

Can you augment your comments by adding the information sources you were using? For example, were you using blockstack.org or gleaning from the UI interaction. How about docs.blockstack.org or app.co — were you using those as information sources or our github repos?

(Yes, those are a lot of information sources. Consistency among these varied sources is something we are working on.)

#4

Yes, you’re absolutely right. In my country, all normal people (I know) need help to install Blockstack, create a Blockstack ID, etc.

We have a page which teach people step by step to install Blockstack… https://blockstackvn.org/blockstack-co-ban/huong-dan-cai-dat-blockstack-va-dang-ky-blockstack-id-mien-phi.html/

#5

I don’t know if these exist but I think having three different 2-5 minute “PR” videos for:

  • the normal end-user (layer 1 - authentication, account management, interacting with apps)
  • the developer (layer 2 - libraries, nodes, and interaction with browser/gaia/etc)
  • the scientist (layer 3 - whitepapers and underlying technology; stacks/atlas/core/etc)

would help immensely with issues like these. @nguyenloc’s tutorial looks pretty good but only covers an introduction/setup of Blockstack, and doesn’t even seem to go into a basic understanding of how it works.

I personally only understand it because I read and re-read the whitepaper 3-4 times and did a presentation on it at university (but I’m behind now regarding Stacks and the deprecation of Atlas… it’s all quite confusing really).

I think documentation is great for detailed explanations of specific items but it doesn’t help you wrap your head around the big picture and how things interact. For that, heavy-reading blog posts or 5-10 minute long videos are much more effective in my opinion – though I may be wrong.

(For instance - there may be a 1-2 minute setup video, but a 5 minute video giving the user a tour of the technology at a surface level, and then a 10 minute video giving a tour of the tech to a developer, then a 30 minute video giving a tour of the tech to the scientist (in more of a lecture sort of format). These are just ideas though.)

Having text specify what the different fields and passwords are for would be helpful though…

1 Like
#6

Yes, that’s why I made over 60 videos to explain Blockstack whitepaper. https://www.youtube.com/playlist?list=PLWTXR68_y97cIePcfTwtg_sxsmz6NssOJ

Anyhow, normal people don’t need to fully understand Blockstack, they want something simple to use - like the iPhone.

Many people told me that using Tor is quite easy compare to Blockstack…

3 Likes
#7

That’s insane!

And I agree - they normally just want to know what it is and how to set it up, perhaps even the why behind it – but nothing too technical.

I would agree that ToR is a little easier to understand because it’s easier to break down:

on desktop:

  • Download the Tor Browser and use it.
  • Congratulations, everything is the same except you are anonymized!

on mobile:

  • Download the Orbot & Turn it on
  • Use Tor Browser
  • And we’re done!

Blockstack on the other hand has a slew of different features then what people are used to (such as what is outlined in this post):

  • I download the “browser” but it’s an application that runs in the background on my desktop? That’s not a browser, that’s something else…
  • I navigate to the “browser” through chrome… what? So it’s a fancy web page that runs on my computer? (also it turns out I never needed to download it and I could just use the browser.blockstack.org instead?)
  • I create an account but I need to store this recovery key? Odd but okay…
  • How do I log out? Why can’t I reset my password (/recovery key) via email?
  • I am recovering my account from a while ago but I have to use this secret key instead of a normal email + password login - and I have to make a new password? And re-enter my email again? What? Why do I even have a password if I never use it?

I tried to solve the first two issues by building an extension, but nothing except for explanation or tutorials will solve the third to last ones as it is what makes Blockstack accounts different from your standard centralized ones (though storing an encrypted email would help with having to re-enter it every time).

1 Like
#8

Can you augment your comments by adding the information sources you were using? For example, were you using blockstack.org or gleaning from the UI interaction. How about docs.blockstack.org or app.co — were you using those as information sources or our github repos?

Most of my confusion has come after being exposed mostly to the UI itself, docs.blockstack.org and https://blockstack.org/install/. I started by reading the ‘Hello, Blockstack’ tutorial specifically.

I didn’t know about app.co until you mentioned it, but that looks really nice. I’m curious, the home page of blockstack.org seems designed to communicate with developers first and foremost, is there a dedicated landing point for regular users?

The docs does explain a little bit about the Blockstack Browser, but https://blockstack.org/install/ is very sparse in information. It is not clear what the benefits or trade-offs are between using the webapp or the downloadable client, even from the docs pages. That translates into a ‘I’m not sure what I’m doing or what I’m going to get’ feeling.

1 Like
#9

Thanks all, I’m very encouraged by the constructive engagement.

2 Likes
#10

@PeterKnight We (mostly @moxiegirl) are currently rolling out docs which you can find here: https://docs.blockstack.org/ though it looks like you have already perused them:

There are also some direct links to API refs here:

Explanations and visual education of the onboarding flow, as well as how blockstack authentication works needs to be overhauled in a way that users can understand how it is different from applications they might be used to using, quickly and intuitively without having to dive into technical APIs. We have identified that as an issue already and are actively working on this. Thank you for bringing it up. We are always looking for feedback.

Understanding how the “browser” facilitates auth flow as a standalone entity or in the web app and what the expectations are for passwords can be more clear as well.

One thing that can be more clear is that the password will be unique to each instance of a login. For example, the password for logging into Blockstack on chrome, will not the same as logging in on firefox, or the blockstack browser if you download it as a stand alone browser as opposed to using it in another one. This may be the issue with your password not working, if you were trying to log in from a different browser than previously. The fact that this is not obvious to you is an issue for us, so thank you for the feedback.

@moxiegirl among others are collaborating to make the auth flow more clear from a developer persepctive as well as a user perspective. This feedback is helpful.

I hope the resources above are helpful, but I understand they need to be easier to find and we shouldn’t have to necessarily point them out to you after alot of frustration. Let us know if you have feedback on the docs.

There are multiple blockstack app tutorials there. Also, if you are building an app right now, check out radiks, released late last week: https://blog.blockstack.org/introducing-radiks/ it might be of interest to you.

In regards to seeing old and outdated issues, we have just overhauled in the past quarter how we triage github issues and open issues. So we are actively working through our iceboxed and otherwise backlogged issues this current quarter at a much higher rate in a much more effective and organized way than previously, and this should be noticeable soon, as we drill down from highest priority issues to all of the backlogged ones, though it is a work in progress.

We hope you are still interested in developing on Blockstack, and you are welcome to come to our Engineering meetings on Wednesday mornings at 10am EST. We post the agenda on the forum in advance and we encourage developers to attend, participate, ask questions, discuss PRs, and give feedback there as well.

Also, feel free to hit us up on our slack, so you are not stuck on something for a long time feeling frustrated without getting the info you need. Regardless, I acknowledge you shouldn’t really have to do that in the first place.

Thank you for helping us get better insight on how to educate users and developers better.

3 Likes
#11

I agree we should consider funneling people to app.co as a source of information on finding existing apps both for developers and users. @moxiegirl is something we can have in the docs? I think there is a link to it after someone finishes the tutorial, but I agree it could be more to the forefront or even a section in the docs could be added “explore the blockstack dapp ecosystem”. I also think if people cannot explore dapps easily from the blockstack landing page when they login to blockstack directly (as opposed to authing through an app first) it will be hard for them to engage if all of the dapps are not available on the profile page.

#12

@PeterKnight thank you for the response and the additional pointers. The major thrust of your original post seemed to be in confusion around identity, onboarding, and the browser as a user.

The other main thrust, though apparently less commentary was your experience as a developer, trying to learn more about app development.

Both viewpoints represent two sides of Blockstack’s goals, we want to drive developers and users into a use of Blockchain technology. In general, it is fair to say our goal is to attract developers in the hopes that these developers will create compelling applications that draw end users.

Because we are focused first on developers, our sites, blockstack.org in particular and docs.blockstack.org to a somewhat lesser degree, are targeted to developers. This is likely why “what’s up with my identity” questions are not easily answered via the sites and you are relying on the onboarding experience. Thank you for your suggetions on expanding the user material. They are absolutely reflected with planned future developments in the docs. You and anyone in the community are always welcome to file or comment agains issues in the source repo,. Please feel free to submit PRs also, if you have material you’d like to write yourself.

The blockstack.org site is under redesign so please watch that space. That redesign is still developer focused but is driving readers who are developers to the Zero-to-DApp tutorial. This tutorial explains Blockstack, our App Mining program, App.co submission, and introduces developers through a sample application to our development environment.

Radiks is a relatively recent soft release by a developer on our team, I would not recommend starting there, though later it would be appropriate if your application requires indexing. Simply put, there is no documentation on docs.blockstack.org and while strong functionality, you won’t encounter it in any of our first use tutorials.

The focus on the application user from our blockstack.org perspective is something we are shifting over time. Case in point, when I joined less than a year ago there was near equivalence portrayed between the web browser and the installed browser. The presentation shows preference for the web broawer over installing now. We definitely can add more emphasis. So, that is definitely a work in progress for us as a team. Searching onboarding on this forum alone can reveal several avenues and area for where we would welcome everyone’s additional comments.

@jeffd and his team are doing a lot of user research and redesign to onboarding. While not perfect we are definitely making inroads compared to the design this time last year. I’m sure Jeff will comment on this thread when he has time.

@nguyenloc thank you for posting the example of your onboarding docs. They are reflective of just how far we have to go and how far we have come in the time since you wrote them.

@MichaelFedora thank you for this:

I tried to solve the first two issues by building an extension, but nothing except for explanation or tutorials will solve the third to last ones as it is what makes Blockstack accounts different from your standard centralized ones (though storing an encrypted email would help with having to re-enter it every time).

The issues Blockstack is trying to solve are not easy issues. It is not just onboarding a user to use an application. We are trying to make them comfortable with a whole new way of using applications and data ownership. It is a hard problem to solve but discussion and feedback are moving the needle…hard to see in the moment, but definitely happening.

6 Likes
#13

Thank you very much for all this, @retired_user

Ahhhh, I see, that clears a lot up. I’ve now read the docs on Blockstack ID in more detail, but I’m struggling to find an expanded explanation on how passwords are used. I think one of the stumbling blocks is that ‘restoring an ID’ sounds like the user has messed up in some way (by forgetting some detail, like a password), rather than a conventional way to establish a session in a fresh browser. When prompted to set a new password, I wondered if it was overwriting the initial password used while creating a Blockstack ID (though now I understand that password wasn’t stored in any shape or form in the first place).

We hope you are still interested in developing on Blockstack

Very much so, I’m looking to build a first experimental app with Blockstack in the coming weeks, the to-do and hello, blockstack tutorials are a great help. I’ll be monitoring Radiks as it would fit well with the more complicated app I’ve been developing (once it supports real-time updates).

Thanks again

1 Like
#14

@PeterKnight awesome!

I agree I would say the verbage around user sessions, passwords and the traditional use of “recovery” is very confusing and should if not reworded entirely, have some serious embedded user education in the onboarding flow of this. @jeffd focuses on user onboarding alot so we getting this feedback to him, and working on making it more obvious in the docs as well.

Still, I think one should not have to read through technical docs to learn how to log in, log out, and relogin somewhere else, and know they need to keep track of multiple passwords, and what the recovery process actually does.

Radiks is experimental and made by Hank Stanover who is an experienced Dapp developer. Agreed with @moxiegirl it qualifies as experimental due to the recentness of it, but I threw it out there as you seem a bit more experienced of a developer, and it might help you with some solutions you are looking at.

Definitely consider our app mining program as well, and let us know if you have trouble getting info on it, we are working to stream line that process as well.

When you speak of your app having real time updates, are you implying you are working on that now, or waiting for Blockstack to provide support for real time updates?

#15

When you speak of your app having real time updates, are you implying you are working on that now, or waiting for Blockstack to provide support for real time updates?

I’m referring to the Radiks framework readme on github, which shows that ‘real-time updates’ are still in progress. That’s a feature I’d need for the collaborative features in my app.

1 Like
#16

Hey, great point. I’m working on a revamp of kanstack.com using Radiks, and real-time is also a requirement for proper collaboration. Realtime support is something that I expect to be the next major addition to Radiks. I would say with confidence that I’d like to have that functionality built and documented within a month. If you need it sooner, hit me up on Slack and we can work that out!

2 Likes
#17

Awesome!

1 Like
#18

I have exactly the same experience as OP. The terminology used by Blockstack is non-standard, confusing, and inconsistently used. But apart from multiple violations of the principle of least surprise, there are simply too many identity-related constructs. As a user, I may have an Id (aka Username), an identity address, a recovery code, a recovery key, a private key, and multiple passwords (valid in different contexts). This is too much. Some refactoring of the architecture seems to be called for here, in addition to better naming and UX improvements.

3 Likes
#19

Hi folks, I think you are making really good points about terminology. We are all working on that. Please go ahead and list any inconsistencies you find particularly egregious.

From reading this post, some terms that are confusing are:

  • browser as applied to Blockstack browser
  • App Mining

We have an existing glossary of terms here:

1 Like
#20

45%20PM
Screen Shot 2019-02-13 at 11.02.45 PM.png1346×466 70.7 KB

18%20PM
Screen Shot 2019-02-13 at 10.45.18 PM.png1336×316 42.5 KB

51%20PM
Screen Shot 2019-02-13 at 10.43.51 PM.png1094×146 10.5 KB

Is nguyenloc.id my username on Blockstack? or nguyenloc is my username in the .id namespace on Blockstack? I’m confusing.