Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Review getting started guide #2060

Closed
12 of 13 tasks
chrisys opened this issue Aug 25, 2021 · 2 comments
Closed
12 of 13 tasks

Review getting started guide #2060

chrisys opened this issue Aug 25, 2021 · 2 comments
Assignees

Comments

@chrisys
Copy link
Member

chrisys commented Aug 25, 2021

The getting started guide in the docs should be the golden path to get up and running with developing using a device on balenaCloud. We have other getting started guides but this one is specifically a guide to getting up and running with development.

Things to consider and approaches to take:

  • Create one definitive path from start to finish
  • Avoid distractions - the path should be clear without forks requiring the person following to make a decision they aren't yet informed enough to make
  • Any links should open in new tabs/windows to avoid losing the guide #2621
  • Remove any 'advanced' usage notes or sections and move them to the appropriate place elsewhere in the docs
  • Remove typescript option for hello world app
  • Remove download OS config file description
  • Shorten paragraphs whilst retaining important information
  • Consider moving 'note' sections out of the flow and off to the side in another column
  • Use consistent naming for example fleets e.g. 'Your-Fleet'
  • Ensure the user knows to select and flash development mode image (see also: https://github.com/balena-io/balena-ui/issues/5044)
  • By the end of the guide the user should have a fleet, a device, an initial release, have pushed an update and know how to develop in local mode. They should be developing (i.e. editing source code and pushing changes) and know how to continue from here on their own.
  • At the end of the guide give a clear path to continue, don't just give a load of options
  • Remove troubleshooting notes and put them out of the flow of the getting started guide somewhere else in the docs (if we don't have them already)

Reference: Alex uses balena notes

@chrisys chrisys self-assigned this Aug 25, 2021
@vipulgupta2048 vipulgupta2048 self-assigned this Aug 26, 2021
@chrisys
Copy link
Member Author

chrisys commented Aug 26, 2021

I'm not sure the item about giving a clear path to continue is still relevant if we've moved the development flow to the getting started guide. We've shown the user everything we wanted to at this point so to a certain extent it is up to them where they go next. 🤔

@vipulgupta2048
Copy link
Member

Created an issue for items pending. Closing this as mostly covered by #2613

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants