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

Reorganize Landing pages for Shipwright website #24

Open
adambkaplan opened this issue Mar 10, 2021 · 0 comments
Open

Reorganize Landing pages for Shipwright website #24

adambkaplan opened this issue Mar 10, 2021 · 0 comments
Labels
kind/documentation Categorizes issue or PR as related to documentation.

Comments

@adambkaplan
Copy link
Member

Thanks for the ping! Perhaps unsurprisingly, I do indeed have thoughts about this 😄

I think a good README or landing page follows roughly the form:

  1. Here's what it is, in a sentence or two ("Framework for building container images on Kubernetes" is great 👍)
  2. Here's what it can do for you -- here's how easy your life will be if you try it
  3. Here's how to start using it -- a simple mini-tutorial, with links to deeper tutorials
  4. Here's how it works, if you're interested -- maybe just a link to architecture.md
  5. Here's how to get involved, if you'd like to contribute

Each step draws the reader in a little deeper, and the user can stop at whatever level they want if they don't care about the next level. (FWIW, Tekton's docs also aren't perfect here, but we try -- Shipwright's API is a lot simpler than Tekton's, so I think we can make the docs really smooth)

"How it works" is purposefully low on that list. Users don't care and shouldn't care how it works (until it doesn't 😅 ), but a lot of docs written by engineers want to jump straight there.

I might send some docs PRs to try to achieve this, if this outline sounds good.

Originally posted by @imjasonh in shipwright-io/build#441 (comment)

@adambkaplan adambkaplan added the kind/documentation Categorizes issue or PR as related to documentation. label Mar 10, 2021
@adambkaplan adambkaplan added this to the release-v0.4.0 milestone Mar 10, 2021
@adambkaplan adambkaplan removed this from the release-v0.4.0 milestone Apr 7, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind/documentation Categorizes issue or PR as related to documentation.
Projects
None yet
Development

No branches or pull requests

1 participant