Samples: README files duplicate the sample files about docs

[rgregg]

We did this for the hello world samples intentionally -- based on feedback we received from Kelsey that simple hello world samples are better understood when the user actually enters the code.

We could remove the code files, and only have the contents in the README file, but I think there's some benefit to having the code around as well (say, if you don't want to type it all in).

I'd love it if GitHub had a way to embed the contents of a file into a rendered markdown file. Then we wouldn't have to try and keep the files in sync. However, it seems like GitHub has closed the request to support that scenario.

[steren]

Yes, I also recommend having users understand the samples instead of cloning a repo for getting started tutorials, however as you said, it would be preferable to embed instead of duplicate the content. What about linking to the files from the README instead of embed ? Also, at one point we can decide to move to a webpage base tutorials (e.g. GitHub pages), which could support code embed.

…

On Mon, Jun 25, 2018, 20:40 Ryan Gregg ***@***.***> wrote: We did this for the hello world samples intentionally -- based on feedback we received from Kelsey that simple hello world samples are better understood when the user actually enters the code. We could remove the code files, and only have the contents in the README file, but I think there's some benefit to having the code around as well (say, if you don't want to type it all in). I'd love it if GitHub had a way to embed the contents of a file into a rendered markdown file. Then we wouldn't have to try and keep the files in sync. However, it seems like GitHub has closed the request to support that scenario <github/markup#346>. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#18 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAWBv2vXY_-1seOdsf9Ft8DDUT_1Ua2zks5uAa0QgaJpZM4U3F1q> .

[rgregg]

Yes, for now I'm going to optimize for readability over our (contributor) maintenance costs. Agree that long term we should have a better way of making this work, and I think when the samples move to a web page we'll have more options for embedding the code and reducing the duplication. For now, I'm not overly concerned.