My beginner experience / improving onboarding process

[MrMinimal]

• [X] I searched for similar feature request and found none was relevant.

Pitch us your idea!

Improving documentation to be more user-centric

Description

Hi,

I love this watch and this is my way of documenting a typical first time user experience. I'm sharing this because once you get into the project, you quickly forget beginner struggles. During setup I made an effort to document everything I thought to improve the docs.

This is not intended to sound mean, the community is amazingly helpful and the people are really kind. I just want to improve the onboarding process by providing typical beginner thoughts.

Expectations

When I bought this watch, my expecation was to have a watch with basic functionalities which I can change some source code on. Since the manual recommends updating the firmware, I went looking on how to do that exactly.

• What is the right OS for me?
• What device do I need for flashing? What app?
• Where can I download the latest firmware?

A Google search lead me to the GitHub README, which is an appropriate source of info for a hacker watch.

README

As I was being greeted by a gigantic logo, I felt overwhelmed. The README currently has lots of links, many of which contain similar information and they all focus on development and debugging straight away. I got stuck in analysis paralysis because I was presented too many options and alternatives.

Since the sealed version aims at casual techies, I recommend a more user-centric README. Developers will dig into the docs anyway.

Onboarding could be split into multiple steps:

1. This is a community watch, if you need any help at all contact us here
2. How to get your PineTime working for the first time
3. This is the latest stable firmware in case you are just a casual user
4. Here is how to flash it on Android, iOS and Linux
5. FAQ when things don't work out

The README is a place to get novices into the project. It might even be a place to promote the watch to users on the verge of buying it. Development documentation should be a level deeper, I always think of the README as a pamphlet.

Development

If you get the users to a point where they have a working watch with the latest firmware, they might be interested in developent. I still recommend keeping the friction to get into development as low as possible (don't install anything locally, get started using GitHub Actions).

Any step that might sound trivial to you but "install SDK on Linux" might be a showstopper for a beginner.

Possible steps for development onboarding:

1. Differences between sealed vs development kit
2. How to use GitHub actions to fork and get your first custom .zip loaded onto your watch (reduce effort to get going by not having to install anything)
3. How to introduct a simple change (e.g. font color) and let GitHub recompile
4. How to setup a local environment using the most simple method (Docker devcontainers probably)
5. How to debug in case anything breaks (development kit only)
6. How to "unbrick" your device if you flashed something really bad

Problems I had

Not intended to sound mean, these can all be cleaned up to make it easier for people to join development.

As a casual user

• README is quite long, I was only looking for a getting started but read everything in case it's important to not miss anything.
• Took long to find the relevant information to download and flash firmware. Lost in development docs.
• No idea which app is the best to flash new firmware -> went for Gadgedbridge worked fine. Recommended.
• Watch was not findable using BLE (stock firmware 1.0.0). Only restart fixed that for me - no documented.
• Docs say to use Gadgedbridge to flash but there is no option in the app. What you acutally do is open the zip in your phones file browser and select Gadgedbridge to open it. Confusing.
• Didn't tell me to download and flash a zip-file. Talks of binary made me expect a .bin file or something similar.
• Some information was almost identical and I didn't know which one to use
• Difference between sealed and development kid barely stated - I was very confused about the debugging part as that is not relevant to me.

As a developer

• All of the above still apply - any dev starts out as a user, not the other way around
• The docs recommend to flash the firmware without any bootloader for debugging purposes - I have a sealed version, so no debugging available and if I flash a firmware that bricks my watch, I can't do anything about it.
• The docs tell you to install all dependencies, SDKs, set up debugging etc. manually only to mention in the end that there is a all-in-one solution if you use devcontainers
• I have a sealed watch and can't really debug anything it turns out. Guess I'll wait for more dev kits to become available.
• No emulator available, I have to have a development kit (don't know if that is even possible with embedded programming)

Summary

I LOVE THIS COMMUNITY! Everyone was welcoming and helpful when I had questions and my custom firmware has an uptime of 7 days already. PineTime and InfiniTime get recomended to everyone I see - I love it.

But I also realize that if I wasn't a developer, I would have never flashed a custom version of InfiniTime on my watch. Acutally I was very close to just leaving the default firmware on it after being confused in the beginning.

Hopefully my ramblings are of use to the team if the docs get an overhaul in the future, I really want more people to be able to experience this amazing piece of hardware.

Thank you for your time and greetings from Germany

Tom

[Avamander]

Quite a bunch of these topics are documented on the wiki (or should be documented there) and not really specific to InfiniTime.

[MrMinimal]

@Avamander You are absolutely right, hey are. But it would be nice if InfiniTime covered them regardless to prevent users from having to search for them im multiple places.

Also I expect your documentation to be more up to date than the wiki because it resides next to the code.

[Avamander]

I disagree, it's already a lot of effort to maintain general information in one location. InfiniTime should document things very directly related to it, not things such as which other OS to pick.

[MrMinimal]

Okay, I will also forward these points as well. Still, there are points which are valid for InfiniTime.

[JF002]

@MrMinimal Thanks for these constructive feedbacks!

Most of these topics have probably already been covered in the chat, github issues/pr, in the wiki or in the forum,... I agree that the end-users, new contributors or developers probably expect to easily find all the information they are looking for in a single place. And I agree with you, the doc definitely needs more love : it needs to be updated, adapted for end-users, new contributors, developers,...

However, the current state of the documentation and of the README.md file reflect the history and the dynamic of the project : at the beginning, it was a single developer (me) project, then a few contributors joined, then more contributors joined, then more and more users joined the party,... That's why you'll find more low-level and advanced info about the development that simple instructions for the end-users. The project evolves very quickly, and we cannot keep up with the documentation. We are trying to improve on that topic in the documentation project. Give us some time, and help us if you can, and we'll improve :)

Also, "PineTime" is an open source project : users have the possibility to do whatever they want with their device : choose the variant (devkit/sealed) they want, install the OS of their choice, modify the source code of an existing project or create a new one,.. These topics are probably very interesting for the users and developers but are out of the scope of this repo. These info should probably be in the Pine64 wiki, for example (which your are free and encouraged to contribute too :) ).

Anyway, thanks for your feedback, and I hope it'll motivate a few contributors for help with the documentation (we are trying to organize it here) and feel free to join us if you think you can help ;-)

I LOVE THIS COMMUNITY!

<3

[MrMinimal]

Thank you for the input, great links as well. I'd love to help out if enough people think this is a good idea.

[Bugsbane]

@MrMinimal I love your idea and agree wholeheartedly. If it's felt that some of what you're proposing is out of scope for InfiniTime's readme, perhaps another way around this would be to add a "Quickstart" guide somewhere else (PineTime wiki?) and then at the start of the ReadMe here adda link saying something like "There are many different ways to get started, but heres a link to a quickstart guide using the recommended settings [LINK]." Then all of the other stuff currently there (that is still relevant) could follow.

[JF002]

I'm closing this discussion. Feel free to re-open if you want to add something.