spring-2017 icon indicating copy to clipboard operation
spring-2017 copied to clipboard

Technical Writing week exercise - Readme for HaCS

Open PandelisZ opened this issue 7 years ago • 2 comments

This commit is based on some of the things learnt in the campus-experts technical writing workshop. An image has been added to make the readme more visual, the description provides context for the repo and there has been a contributing guideline added. Build and test instructions we're simple and straightforward enough i believe so they remained the same

PS: totally just used cherry picking for the first time to make this PR cleaner. Super cool The guide used

PR which adds this readme: https://github.com/HaCSBCU/hacsbcu.github.io/pull/27

PandelisZ avatar Apr 27 '17 21:04 PandelisZ

And for good measure, I've jazzed up the discuss repo readme too

https://github.com/campus-experts/discuss/pull/4

And this one. Not gonna lie, really proud of this one 😆

https://github.com/campus-experts/awesome-campus-expert/pull/8

PandelisZ avatar Apr 27 '17 21:04 PandelisZ

:+1: this is great, as were your other readmes. The only thing I'd say here, to bring in my feedback of your impact proposal as a whole, is that with your website there will be a lot of concepts totally alien to a lot of students. I don't know if the readme of the website itself is the place to address that, but it might be worth linking to an external document. Even reading what the website is, a horde of questions will arise:

  • What is Jekyll?
  • What is a static website?
  • Where do I run these commands?
  • What's gem? what's bundler?

Etc etc. Obviously you need to assume some knowledge somewhere, but it might be worth including a minimal "this is Ruby, this is a static site, here's where you can find out more" paragraph

joenash avatar May 12 '17 09:05 joenash