draft-classic icon indicating copy to clipboard operation
draft-classic copied to clipboard

Feedback: The README should be more tech-focused

Open bacongobbler opened this issue 7 years ago • 2 comments

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:

  • 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

bacongobbler avatar Mar 27 '18 00:03 bacongobbler

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.

keithalpichi avatar Apr 29 '18 01:04 keithalpichi

I'll see if I can tackle this today.

bacongobbler avatar May 18 '18 16:05 bacongobbler