You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
Here's what it is, in a sentence or two ("Framework for building container images on Kubernetes" is great 👍)
Here's what it can do for you -- here's how easy your life will be if you try it
Here's how to start using it -- a simple mini-tutorial, with links to deeper tutorials
Here's how it works, if you're interested -- maybe just a link to architecture.md
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.
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:
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)
The text was updated successfully, but these errors were encountered: