New User Onboarding is Missing

[visualcurrent]

Maybe you are intentionally culling potential users at this early stage. I can't tell, because your website looks welcoming. But I can't find any useful instructions to get going. This is the second time I've tried installing OwnTracks and I'm giving up again.

Just in case you do want to expand your user base, I'm reporting my experience here. OwnTracks looks wonderful. I hope this helps you when you're ready to open up to more users.

The only quick instructions are on the main webpage:

To get started, install OwnTracks on your smartphone. Afterwards you can connect it to an existing server straight away.

Okay, looks easy. I try that.
But it doesn't work.

"...straight away?" Hardly! A new user has no way of knowing how to connect to an existing server. Looking again in the Booklet, there's just nothing I can see to help a user actually get going under the following seemingly appropriate sections to read:

• Intro
• What it does
• Clients
• Apps
• Broker
• Android
• Android>Setup (Really?! Not even in the Setup section!)

The level of advanced detail is appreciated and probably great for seasoned users and programmers, but don't you want other open-source aware people to join the community and use this?

Okay, so I try to charge forward blindly and enable permissions during the initial setup screens.

I see my location on the map -- Good. I research Location Data Modes to figure out what they are and find them a little bit buried in the Feature Section -- Okay. Then I notice the persistent notification and it says "Configuration Incomplete." Didn't I just successfully traverse the setup screens???

There's just no information to resolve this. Clicking on it doesn't lead anywhere but the map, so that doesn't help. Furthermore there's some button in the notification "CHANGE MONITORING" which does absolutely nothing when we click it. Is it related to an incomplete configuration? Who knows??? There's no indication that it does anything.

This is where I said "Screw this!" the first time and uninstalled the app. This time I continue messing around and by chance, I notice that CHANGE MONITORING toggles the Tracking Mode, which by the way doesn't appear to have a consistent feature name. Nowhere in the Location Data section are these modes collectively classified as or referred to as MONITORING. There's a different feature called "region monitoring" which only adds to the confusion. May I suggest classifying all of these modes under a common term that's clearly published in the documentation as a section title and used in the app. I would suggest "Tracking Mode" -- seems appropriate. "Monitoring Mode" works as well.

Coming back to the CHANGE MONITORING button that appears to do nothing. Are you expecting users to somehow memorize the order of a quadruple toggle? And also memorize the toggle state that was last set hours or days ago? I hope your general UX sensibility says no.

The nicest UI for this would be to update the OwnTracks icon in the notification bar to show the existing icons used for each tracking mode. That would provide the easiest state feedback. If the OS doesn't make that easy, you've got to add something to reflect the toggle state in the pull-down notification box.

Coming back to the reason I'm ditching this app a second time. What is this incomplete configuration?!!!! What an aggravating experience this is! Me, loving the idea of this app and really wanting to make this work, I search the github issues and all I find are #490 and #609. The only advice is to,

set a username in the connection preferences

Okay, so maybe it is that easy. I find Preferences>Connection>Identification>Username and Password
and fill those lines in
.... Nothing
.... No feedback
.... Am I creating an account here? Am I supposed to already have a UN/PW from somewhere? Is this UN/PW combination simply acting as a decryption key and nothing more is needed?
No idea? But whatever it is, there's no feedback and the despite the simple sounding advise provided in issue #490 and #609, my configuration is still incomplete and there's no allusion to where I might find instruction for this.

I know this all sounds like a complaining rant. But I believe each of these issues have rather simple solutions in cohesive documentation and (with a little more effort) minor UI adjustments.

When you are ready for users, please consider lowering this seemingly insurmountable bar of entry with a dedicated and installation-process complete quick-start section in your Booklet or website. Or if you are intentionally deflecting users, please have the courtesy to state on your webpage that potential users shouldn't bother with OwnTracks unless we have experience running our own server or whatever gatekeeping bar of entry you are setting for this app. It's hard for me to imagine that this is the intent, but it kinda feels like that.

Maybe I'm glossing over some essential and obvious information. But I feel like I've given it an honest effort without any reward.

• App build number: 2.3.0 (23025)
• Android version: 8.0.0
• Device: LG V20

[growse]

Thank you for taking the time to write this. I understand where you're coming from and agree that there are certainly places where the app's hard to use, does something surprising or isn't particularly clear about what it expects from the end user. Sometimes we all get a bit close to things that we've worked on for a while, and we lose the ability to empathise easily with someone looking at it completely fresh.

I think there's two broad areas that you've pointed out which, if addressed, could see some real benefits at not a huge amount of cost:

1. I'd personally like to see a complete novice guide which takes someone through setting up a recorder endpoint on a cheap/free infrastructure provider and then hooking the app up to it so that they can get a feel for how it works. There's a small handful of things that might need to be done (e.g. Disable MQTT if port == 0 recorder#366) to get the necessary bits in place and then it's just a question of writing the actual words. There's also more we could do to make it clear that OwnTracks is not a "service" you sign up for, but needs different components to be set up and managed. For some users, this will be beyond their capability. For everyone else, it should be as simple as possible to get started.
2. The Android app UX could definitely be improved. I've always been hesitant to make any changes to the UI, mostly because a) I'm not an expert in usability - what I think is sensible might not actually be, and b) there's a non-zero number of users who interact with the app every single day, so any change is a cost to them in terms of re-learning something that's different, even if the change is for a very good reason.

I'm going to try and take some time to break this down into a specific list of small tangable things we can do individually to the Android app and maybe create an issue for each one to try and get into 2.5 (2.4 is nearly done). As ever, pull requests and issues are welcome, so if you do spot something that you think could be better and you're comfortable with knowing what the change needs to be, please raise it. If you're not comfortable or unsure with where the change might need to be made, please raise an issue specific to that change. For usability changes and the like, it need to only be a few lines, and that can then be the starting point for a discussion. Imposing change unilaterally usually makes me feel comfortable, but a decision after a discussion about the best way forward is often better.

Once I get that list together, I'll open some issues and close this one (will also try to link to this one from them so we can track).

At the end of the day, this app (and the whole OwnTracks project) is maintained by volunteers with a full-time jobs and other lovely time-sinks (children! argh!), so much as I'd love to devote a large amount of time to thinking about and making lots of improvements, finding small pockets of time to take little nibbles out of things is the sort of rate of progress that might be expected in the forseeable future.

[boogymantoo]

1. I'd personally like to see a complete novice guide which takes someone through setting up a recorder endpoint on a cheap/free infrastructure provider and then hooking the app up to it so that they can get a feel for how it works.

Hi Andrew, about that 'request' :

• are you referring to a setup that uses this recorder specifically?
• if not, should the guide cover a setup that uses MQTT (or would http(s) be OK)?
• what should be the 'primary focus' of the tutorial - setting up a recorder, or how owntracks (and its flows) works?

Thanks,
Chris.

[jpmens]

I should think a novice guide will first explain why this all exists and what can be done with OwnTracks, followed by how to set up the OwnTracks Recorder in HTTPS mode (as that's the protocol with the fewest moving parts), connect a phone or two, and get our Frontend set up to view maps. I think while going through this, the terminology we use in OwnTracks could be explained.

Adding to the guide, we could maybe "gently" explain what MQTT is, how people can benefit from it, and the difference between using OwnTracks with MQTT and HTTP.

Particularly the first part ought to flow a bit like a "story" -- I think that's a major failure in the documentation we have so far in the Booklet.

[growse]

There's space here for multiple things for multiple people. Some people learn by reading, some people learn by doing etc. Our current docs sort of assume a sort of familiarity with the problem space in general, and that the reader already knows what they're trying to do. I suspect a lot of people looking at it don't even necessarily understand exactly what OT is trying to do, and why some people find that useful.

I personally fall into the "learn-by-doing" category, so if I try and imagine what it would be like coming across the booklet for the first time, my initial reaction will be the same as with a lot of open-source software projects: show me how to download and get started in a basic way, and then if I've got further questions I'll come back to the docs.

are you referring to a setup that uses this recorder specifically?

Yes, just because my perception is that the number of "things" you need to do to get OT on a device talking to OT recorder over HTTP on the internet is smaller than getting MQTT involved.

if not, should the guide cover a setup that uses MQTT (or would http(s) be OK)?

Agree with JP here - a complete novice guide should involve the least complexity, but then once they're set up and can see how the general idea works then hint that there are challenges / drawbacks with HTTP that could be addressed by moving to MQTT. If they want to explore that, we can point to another guide explaining how to get MQTT set up.

[boogymantoo]

When reading both your replies, I "feel" that the guide could/should explore a couple of well-chosen use-cases?

And, for each use-case, explain:

• its problem description
• its solution description (a non-technical description)
• how that solution maps on OT // recorder // front-end
• providing a simplified implementation of the solution and how to set it up?

(Just trying to trigger ideas and reactions here).

If the above sounds like "a start", then the following elements should (in my opinion) find a place somewhere in the story-line:

• choice of monitoring mode (in function of the use-case)
• choice of OT configuration parameters within the monitoring mode (explaining why)
• choice of how to get the OT instances actually configured (could be in function of the use-case)

[...] which takes someone through setting up a recorder endpoint on a cheap/free infrastructure provider and then hooking the app up to it so that they can get a feel for how it works [...]

For that part, I have done a small 'test' - namely setting up an AWS Linux 2 instance, installing a LAMP stack on it, and then deploying a slimmed-down version of the html and php implementations that I wrote, which is used (by an ngo) to track participants during walking events. It's easy, not lightning fast (free tier) but usable, and resource consumption can be kept in the 'Free Tier' for one year. After a year, if you keep the instance running, it will be billed.

To avoid misunderstandings: it is not the OT recorder available on github. In a nutshell, this is the 'journey' and the components:

• visit a web-page (from your phone)
• URL parameters indicate the ID attributes (first name, device ID) and language
• on that page, clicking on a link (one for Android, another for iPhone) will import a complete configuration in OT
• that configuration makes OT send locations periodically to a (php) endpoint
• the code behind that php endpoint will persist the location messages in a very simple db table
• visit a test-page, enter your deviceID, and it will show the locations received from that deviceID during the last hour

I presume that the OT recorder available on github can also be easily deployed and ran on an AWS Linux 2 instance. If the idea of the novice guide comes to life, I am OK to try that out (and document it).

Best regards,
Chris.

[GreyGnome]

I have to agree. There's a whole lot of manual pages describing Open tracks, but I'm trying to get the thing to work with HomeAssistant and it's difficult to figure out what to do. For example, I'm trying to set a region. In the table of contents, there's no chapter for it. Oh wait, I see Waypoints. When I click on it, it opens Regions (Waypoints). I see that the terms are used interchangeably but I also have the impression that they're different. It should be made very clear that they are exactly the same, and the waypoints headings should always have regions next to them, just like Regions(Waypoints) at the bottom. Furthermore, the documentation says that coordinates can be entered by using the place picker but try as I might, I cannot do it. Also, in the map page the third button from the right, at the top, changes mode but I have little idea what the modes do, nor do I know whether the mode just mentioned at the bottom of the screen is the mode I just left or the mode I entered. And the button shape looks like a music player control but I don't think that correlates to what the app is doing. It implies some sort of activity that I don't think is analogous to a music player.

Anyway, it's open source so I get it and I thank you for the work and maybe I can help a little with the documentation rather than just moaning over here. It does take a long time to get going and I have no idea even now if I'm doing the right thing.

[jpmens]

I'm very favorable to the simplistic (if you pardon the term) approach but fear it's a bit too little; I think people will expect maps, so as such it would have to be our Recorder (or something which can produce data for our Frontend). I understand if the thought of "free tier" appeals to people (is signing up for AWS still as complicated / confusing as I recall it being?), but I'm very skeptical of "try this free for now" and then being surprised a year later when the bill arrives. I will admit to being old-fashioned in that respect, though :-)

[boogymantoo]

I'm very favorable to the simplistic (if you pardon the term) approach

No need to apologize - I have kept it as simple as possible, and did so consciously.

I think people will expect maps

Yes, so do I. The reason why our own frontend (simplified or not) cannot be hooked up 'just like that' is the following: in our application, the continuous stream of location messages (delivered in that very simple db table) is interpreted by a rather complicated Python program which actually tracks the participants along a predefined track, and which reports in its output the 'current locations of participants' as well as 'exceptions that need attention'. Our frontend consumes the output of that Python program.

as such it would have to be our Recorder (or something which can produce data for our Frontend)

I could check what data this Frontend needs, and see how easy (or not) those data can be produced from the 'db table'. Just let me know if that sounds like a good idea.

is signing up for AWS still as complicated / confusing as I recall it being?

Well, in my opinion their UI is much more 'technical' than it needs to be. I wonder why they do that.

I'm very skeptical of "try this free for now" and then being surprised a year later when the bill arrives

Very understandable. I made an estimate - how much would that bill be if I forget to shut the instance down? It should remain under 5 dollar per month, and stoppable at all times. I will know in a year :-)