8000 We’re too “smart” for "dumb" quotes · Issue #4347 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

We’re too “smart” for "dumb" quotes #4347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
GeertDD opened this issue Oct 20, 2014 · 10 comments
Closed

We’re too “smart” for "dumb" quotes #4347

GeertDD opened this issue Oct 20, 2014 · 10 comments
Labels
Waiting feedback

Comments

@GeertDD
Copy link
Contributor
GeertDD commented Oct 20, 2014

It’d be great to see correct quotation marks being used throughout the book’s text.

http://smartquotesforsmartpeople.com/
@GeertDD GeertDD changed the title We’re too smart for dumb quotes We’re too “smart” for "dumb" quotes Oct 20, 2014
@wouterj
Copy link
Member
wouterj commented Oct 20, 2014

-1 for the same reason as why we rejected the use of the em-dash. They don't make life easier for contributors.

@javiereguiluz
Copy link
Member

@GeertDD thanks for your suggestion! If we were discussing about novels and books for regular people, the use of smart quotes would be out of question.

But when dealing with technical books, I agree with @wouterj that this over-complicates everything for no real benefit. The reason is that you cannot write those smart quotes with the kind of editors used to write technical documentation.

@GeertDD
Copy link
Contributor Author
GeertDD commented Oct 20, 2014

Frankly, I completely disagree. To learn that em-dashes got “rejected” as well (#1637), makes me even more sad.

Coding web apps may be hard and complicated, but typing curly quotes—or em-dashes for that matter—surely is not. They’re just one keystroke away. I could understand that my grand mom who just bought a computer, with all due respect, might have a bit of a hard time figuring out where the “alt” key is located. We are programmers, though. Please, master your keyboard.

Even if those characters were hard to type, they’re still the correct characters to use. Typography matters.

@wouterj
Copy link
Member
wouterj commented Oct 20, 2014

In some degree I agree that typography matters. However, using the plain quotes or the curly quotes in a text the size of 12px isn't what makes a user have more attention imo. Yeah, it might be for some people (like you), but the fact that you are the first one that opens an issue (in 3 years of Sf2 docs) is a good indication that it doesn't really matter in the type of documentation we're making here.

In the docs we are always fighting against 2 fronts: Having docs that are the best for the reader, making it really easy to contribute. In some cases, we might make the docs 0.00001% less good for the reader to make it easier to contribute (like rejecting the em-dash) and in some cases we do the opposite (like having a big set of standards and conventions).

However, I'm of course not the only one who decides what to do. Let's see what the other doc guys and, maybe more important, the community thinks about it.

@wouterj
Copy link
Member
wouterj commented Oct 20, 2014

We can maybe also tweak the generation process to do this for us? /cc @javiereguiluz

@javiereguiluz
Copy link
Member

@GeertDD in theory these curved quotes are "just one keystroke away":

quotes

In practice I cannot make them appear in my text editor. That's why we said that these complicates everything for a real small benefit. And even that benefit is debatable because if you ask to technical people, a lot of them won't like the curved quotes in technical documentation and they prefer the straight quotes.

@wouterj I'd prefer to not try any automatic conversion process. I'm completely sure that we'll introduce errors. Keep in mind that we should use straight quotes for code, except for the text inside comments; curved quotes for most of the current straight quotes, except if they refer to lengths of units or latitude/longitude coordinates.

@xabbuh
Copy link
Member
xabbuh commented Oct 21, 2014

Just a quick question: Do we really use so many quotes outside code blocks? Can we maybe find better solutions for them instead of replacing them with another kind of quotes?

@GeertDD
Copy link
Contributor Author
GeertDD commented Oct 21, 2014

However, using the plain quotes or the curly quotes in a text the size of 12px isn't what makes a user have more attention imo.

Sure. Just wanted to say, though, that we shouldn’t assume everybody is reading it at 12px. Personally I like to zoom in a bit in the browser, people could be reading the PDF or a printed version, etc.

In practice I cannot make them [curly quotes] appear in my text editor.

Wow. Software like that shouldn’t be allowed to be called a “text editor”.

I'd prefer to not try any automatic conversion process. I'm completely sure that we'll introduce errors. Keep in mind that we should use straight quotes for code […]

Agreed. Unless you want to open up a can of worms, adding correct quotes should be done manually.

All that being said, I guess I’m a stickler for typography. We’re only talking about quotation marks—can you believe I just said that? 😉 If the consensus appears to be not to invest energy in this matter, I can live with that. It’s just that I’m new to Symfony and so far I’m impressed with its top-notch documentation. My hope was to make it just a tad better even. If the docs weren’t on this level already, I wouldn’t have bothered to raise the point of typography. Consider this issue a compliment.

@linaori
Copy link
Contributor
linaori commented Oct 24, 2014

I'm always for good documentation, but quite frankly, I don't even have those characters on my keyboard. Making those necessary in the documentation will:

  • Make it hard to contribute
  • Cost more time to review
  • Slow down the release process

@wouterj
Copy link
Member
wouterj commented Oct 30, 2014

I'm going to close this, since we all somewhat agree that it's almost not worth the hustle...

@wouterj wouterj closed this as completed Oct 30, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Waiting feedback
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@GeertDD @javiereguiluz @wouterj @linaori @xabbuh
0