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

Move long README sections to the book, to make it easier for new users to get started with Zebra #1617

Closed
2 of 5 tasks
Tracked by #2310
mpguerra opened this issue Jan 22, 2021 · 1 comment · Fixed by #4680
Closed
2 of 5 tasks
Tracked by #2310
Labels
C-enhancement Category: This is an improvement C-user-research Category: Tickets related to or arising from user studies

Comments

@mpguerra
Copy link
Contributor

mpguerra commented Jan 22, 2021

Is your feature request related to a problem? Please describe.

From our user studies we discovered that users found the README a bit long and overwhelming and that, after skimming the README, they still asked us about information that was present within.

Describe the solution you'd like

Some ideas/suggestions:

  • Remove information about First Alpha release in favour of some banner or something else that clearly shows that Zebra is currently at Alpha stage.
  • Move "System Requirements" and "Network Requirements" to "Getting Started" section below:
    "Building zebrad requires Rust, libclang, and a C++ compiler." and above "Detailed Build and Run Instructions"
  • Expand on Build and run instructions to include explicit and specific about required package managers for various operating systems and other environmental setup, binaries, etc...
  • Add hints to the "Detailed Build and Run Instructions" section about making sure cargo is in path
  • Link out to Zebra book and provide high level headlines on sections such as "Architecture"

Describe alternatives you've considered

Leave the README as is.

Additional context

This was discovered during our first alpha user studies (#1501).

@mpguerra mpguerra added C-enhancement Category: This is an improvement S-needs-triage Status: A bug report needs triage C-user-research Category: Tickets related to or arising from user studies labels Jan 22, 2021
@mpguerra mpguerra removed the S-needs-triage Status: A bug report needs triage label Feb 2, 2021
@teor2345
Copy link
Contributor

This was on the retrospective agenda today, so I'm going to leave it open.

@teor2345 teor2345 changed the title Restructure and clean up README to make it easier for new users to get started with Zebra Move long README sections to the book, to make it easier for new users to get started with Zebra Jun 2, 2022
@mergify mergify bot closed this as completed in #4680 Jun 28, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: This is an improvement C-user-research Category: Tickets related to or arising from user studies
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants