draft-classic
draft-classic copied to clipboard
Feedback: The README should be more tech-focused
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:
- move the video to the bottom
- 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:
- https://github.com/gorilla/mux#examples
- https://docs.djangoproject.com/en/2.0/intro/overview/
- https://github.com/jakubroztocil/httpie#readme
- https://github.com/ipfs/go-ipfs#readme
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.
I'll see if I can tackle this today.