search

zkevinbai / Alexandria

Alexandria is a book search engine, book tracker, and reading history analyzer.
https://alexandria-book.herokuapp.com/
1 stars 0 forks source link

Replace code screenshots in Readme with snippets #97

Closed sdodonnell closed 5 years ago

sdodonnell commented 5 years ago

I switched out the screenshots with code snippets, which I think are the more industry standard way to go.

sdodonnell commented 5 years ago

Would it be ok if we did snippets instead? They definitely told us to, and I think every other readme I've seen has had snippets rather than screenshots.

zkevinbai commented 5 years ago

Who do you mean by they? The coaches? Eli told me this readme looked great, I don't recall him mentioning snippets during my meeting with him.

sdodonnell commented 5 years ago

Yeah they mentioned in the project intro I think, and this is from the instructions for the fullstack readme on things to include: "Code snippets to highlight your best code (markdown code snippets, NOT screenshots)"

zkevinbai commented 5 years ago

To be honest, I'm not crazy about snippets.

Reasons

  1. Syntax: Github snippets have minimal syntax highlighting and are thus hard to read
  2. Length: Full-length code reduces the chances that recruiters will scroll down to see more code
  3. Audience: Recruiters won't benefit from being able to read all the code, "pretty pictures" alongside descriptions will probably do more for us

The above factors plus the fact that I got no comments about it from my coach, lead me to think that snippets are at best optional.

sdodonnell commented 5 years ago

Are we talking about the same thing? I mean code snippets written in markdown rather than the screenshots of the VS code window. The screenshots of the app are all great.

zkevinbai commented 5 years ago

Yes, my 3 points are all to do with markdown code

syntax: VS Code > Markdown readability: VS Code > Markdown recruiter-friendliness: VS Code > Markdown

sdodonnell commented 5 years ago

Totally fine if you want to keep the screenshots, I'll just clone the repo and host it on my own profile. But I still do think snippets are the way to go:

  1. Markdown absolutely does have syntax highlighting if you include the name of the language after the first set of backticks. It uses as many different hues as the highlighter you use in VS code. If anything, the screenshots are harder to read because of the unevenness with which they get integrated into the flow of the page. Markdown keeps everything under the same style framework, which makes things easier to read on the whole. Plus, one of the main reasons markdown exists is to be able to seamlessly integrate code with other kinds of text.

  2. I'm not sure what you mean about length. It's the same code, and won't be significantly longer. In some cases it may very well be shorter. Given that the code examples (which are all great choices, I should mention!) are not necessarily all that short to begin with, I don't think length is a huge concern.

  3. Three responses. A) Our audience is not just recruiters, but other software developers. This is a part of our portfolios, which could very well follow us around for a long time, and markdown is the industry standard, as far as I am aware. We should keep them in mind as much as recruiters. B) I don't think that's a very fair way to characterize recruiters, whose job it is, keep in mind, to judge applicants' merit based on their GitHubs, among other things. Given that every other repo I've seen (including repos for things like D3, which at the end of the day ought to be our stylistic basis) has used markdown rather than screenshots to display code, it's likely that a recruiter will know that these look out of place. C) Screenshots of VS code are not particularly pretty...quite the opposite. They have ruler lines in them at odd places, they underline all the things they consider bad style (e.g. mission semicolons, of which we have several), and, as I mentioned before, they don't fit with the flow of the page. If what they're looking for is pretty pictures, snippets will go further for recruiters than screenshots.

But as I said, you're totally welcome to keep the screenshots!