search

ga-wdi-boston / talk-template

Other
1 stars 27 forks source link

Make preparation instructions more general #12

Open gaand opened 8 years ago

gaand commented 8 years ago

At https://github.com/ga-wdi-boston/talk-template#preparation

Specifically

 1.  Create a new branch, `training`, for your work.
 1.  Checkout to the `training` branch.
-1.  Install dependencies with `npm install`.
+1.  Install dependencies.

 Better preparation instructions may be found as
 [snippets](https://github.com/ga-wdi-boston/instructors/tree/master/snippets).
gaand commented 8 years ago

Or maybe include "with dependency installation command".

jrhorn424 commented 8 years ago

It's not really the case that the README here is canonical. It's just that a few sections are. I suppose preparation instructions could be, but I don't have a firm opinion on whether or not they should be.

I think I lean toward having an obvious (plain text) variable declaration there, based on the two options given.

If we want the preparation instructions to be canonical (as the license notice and logo are now), I think I'd favor moving that dependencies line as a decentralized FAQ article and link to it in each template. So each template would point to the same FAQ article. That FAQ article would have instructions for each stack, such as "if your repository has a Gemfile, run bundle install".

This is in the same spirit as our "fork and clone" FAQ article and allows us to maintain this portion of the instructions in precisely in one place.

gaand commented 8 years ago

I think this is something we should talk about because we already have many sources of truth. What's the purpose of a template if it isn't at least partly a source of truth?

Maybe there's a scheme that makes sense but I don't want to have to look at a wiki for updating from templates. I want the templates to tell me what to do.