Skip to content
This repository has been archived by the owner on Jun 12, 2024. It is now read-only.

Feedback: The README should be more tech-focused #610

Open
Tracked by #765
bacongobbler opened this issue Mar 27, 2018 · 2 comments
Open
Tracked by #765

Feedback: The README should be more tech-focused #610

bacongobbler opened this issue Mar 27, 2018 · 2 comments
Assignees
Milestone

Comments

@bacongobbler
Copy link
Contributor

bacongobbler commented Mar 27, 2018

I got feedback from a colleague that they didn't fully understand what was Draft until I gave them a demo. Some general feedback was:

  • I didn't press play on the video, and the text is too small. Maybe it should auto-play, or a audio-less video is simply the wrong medium for a README?
  • The first section in the README sounds like something from marketing. It didn't give me the "a ha" moment I was looking for.

I think we can tackle this in two waves:

  1. move the video to the bottom
  2. Make a smaller, more narrow "Usage" guide in the README, much like the current Getting Started Guide we have in the documentation.

Because a large majority of people reading our README are primarily dev-focused, I think a technical example might be a better format for a README. For example:

@keithalpichi
Copy link

I agree. I'd like to add this blog post by Kubernetes as another example to your list https://kubernetes.io/blog/2017/05/draft-kubernetes-container-development.

@michelleN michelleN mentioned this issue May 18, 2018
2 tasks
@bacongobbler
Copy link
Contributor Author

I'll see if I can tackle this today.

@bacongobbler bacongobbler added this to the 0.16.0 milestone May 18, 2018
@bacongobbler bacongobbler self-assigned this May 29, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

2 participants