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

Docs v2: Examples do not list prerequisites and supported environments. #260

Open
jordanmack opened this issue Mar 31, 2024 · 0 comments
Open

Comments

@jordanmack
Copy link
Collaborator

Any sections which have code examples should have prerequisites and supported environments. The ideal would be that all examples and tools will work on the same base environment, and we provide a link to this page where it is appropriate.

We should not make assumptions about the background of the developer or the platforms they are familiar with using. List everything needed. We do not need to explain how to install or use prerequisite software, but we should link to the install page when possible.

Our suggested base environment should include:

  • The operating systems that we support and recommend. (Support and recommendations are not the same thing!)
  • The minimum base software that we expect to be installed. Git? Docker? build-essential? Xcode-tools? List everything.
  • Are there specific things they need to be familiar with in order to use our examples? Linux? Javascript? Rust? We don't have to teach them everything, but we should inform them what is necessary, and link to external learning resources if possible.

Our example code should include:

  • Any requirements or software outside of the base environment they will need to have installed for this specific example.
  • The tech stack being used. React? Vue? Typescript? List the major technology pieces so they know what they are getting into.

The ideal is that example code will not require anything outside of the base environment. The lower the barrier to entry, the higher the developer acquisition rate will be.

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

No branches or pull requests

1 participant