Technical Writing week exercise - Readme for HaCS #42
Conversation
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
PandelisZ
force-pushed
the
hacs-readme-cherrypick/pandelisz
branch
from
bae2227
to
9f0feff
Compare
|
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 😆 |
|
👍 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:
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 |
|
|
||
| Once you have ruby installed: | ||
|
|
||
| `$ gem install bundler` |
There was a problem hiding this comment.
You can use code blocks to make commands on their own line look a bit nicer:
```sh
$ gem install bundler
```
(Which comes out like
$ gem install bundler, instead of
$ gem install bundler
)
|
|
||
| Once you have ruby installed: | ||
|
|
||
| `$ gem install bundler` |
There was a problem hiding this comment.
Something I've come across when introducing beginners to projects is that the $ at the start of a command can be more of a hindrance than a help — if people try to copy and paste the command into their terminal and don't know they have to remove the $ it won't work.
There was a problem hiding this comment.
thanks for the feedback, Might as well remove them
| @@ -0,0 +1,38 @@ | |||
| [](https://travis-ci.org/HaCSBCU/hacsbcu.github.io) | |||
|
|
|||
|  | |||
There was a problem hiding this comment.
Just being picky really but I noticed two things which might be ever so minor improvements.
- With Chrome if you hover in between the address bar and your addons, you get the option to drag the size of your addons menu around. When I'm doing screenshots I tend to crush this down to nothing, it's not nessesary but if you're looking for an extra clean finish it is a quick thing to do.
- The image you're linking to is on imgur, this is just a personal preference thing but I tend to keep even these images within the repo as they're part of your content.
Again, it's super picky and not anything which will greatly improve the readme (because it's already top notch) but maybe something to consider.
There was a problem hiding this comment.
On the image thing I've discovered the trick of posting in an issue to get the github cdn link, so its all within github and doesn't litter your repo.
I used that trick on the awesome repo and discuss
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: HaCSBCU/hacsbcu.github.io#27