A few style questions/decisions

[alimony]

I'm doing some style cleanup of the pages, and am wondering about a few things:

1. Should body text be hard-wrapped or not in the Markdown files? (There's currently a mixture going on in most of the files.) With unwrapped text it would be up to everyone's own text editor to do any soft-wrapping needed to get an overview of the text. On the other hand, if all body text was to be wrapped at (for example) 80 chars, you could edit the files without soft-wrapping, having a good overview of body text, but without getting annoying few-character line-breaks in code sections that span more than 80 chars.
2. How should AJAX be capitalized? As an abbreviation, it could just follow the rule of having a spelled out explanation and the abbreviation in parentheses at first use, then just the abbreviation. On the other hand, Ajax is almost not an abbreviation because of its ubiquity, but rather a proper name. As such, it could always be written as "Ajax". Anything is better than the current mix of AJAX/Ajax, and "ajax" though :)
3. What style should code comments follow? Some of them use capital initial and period now, and some just lowercase (arguably a more "real-worldy" form). Should code comments have a max row length (80 chars)? I think the current mix of styles gives a bit of a messy impression.
4. Should HTML entities be used to encode things like apostrophe, quotation mark, and ellipsis, or should all Markdown and HTML files just use the decoded characters? Having decoded characters everywhere improves readability a lot when editing the files, but might on the other hand "hide" special chars, making contributors insert for example straight quotes/inch marks instead of curly quotation marks, since that looks "almost" like the rest of the text.

Some of these thoughts might seem extremely pedantic, but if you find them worthwhile answering, I think it would be a good idea to add those answers to the existing style guides.

[scottgonzalez]

I'll take a stab at answering these, but then we'll need consensus from the team on some of this:

1. Text in markdown files should not be hard-wrapped. You should write prose as if you were writing an essay. (this needs consensus)
2. Always Ajax. (this already has consensus)
3. See http://contribute.jquery.org/style-guide/js/#comments. However, documentation has exceptions, like comments on the same line for results and some short explanations/clarifications. (this already has consensus)
4. We use UTF-8, as all the world should. No need to encode characters. However, I believe we've been avoiding the use of things like curly quotes because most contributors won't do that so it just presents a maintenance/consistency burden. (this needs consensus)

[ajpiano]

I agree with @scottgonzalez points 2, 3, and 4. I am torn on point 1 and can see the case for both POVs and am curious what others prefer here.

[kswedberg]

I agree with @scottgonzalez on 1-3. For #4, if we want curly quotes, it should be done in some kind of automated build/deploy process—but I'm not sure it's worth it.

[scottgonzalez]

Regarding soft-wrapping vs. hard-wrapping of prose: Hard-wrapping creates unnecessary noise during small text changes. See also https://github.com/blog/1707-soft-wrapping-on-prose-diffs.

[ajpiano]

Yeah, I think a lot of the reason we have a lot of hard-wrapped files in the first place is because the improved handling for soft-wrapped prose diffs is a recent feature, and it used to be an epic pain in the ass to view diffs on GH of soft-wrapped prose.

[tjvantoll]

I agree with @scottgonzalez on 1–4. I'm strongly against hard-wrapping in particular.

We're definitely inconsistent with wrapping in this repo currently, but that's something we can clean up as we go. I found only one use of “ and ”.

[arthurvr]

Point 2 is addressed with 45babf6.

The other points:

1. I'm against hard-wrapping. But at the end that's a personal opinion.

2. We all agree on that, code comments should just follow the style guide. Are there places it doesn't? If so I'm happy to open a PR addressing it.

3. Yay UTF-8.

[scottgonzalez]

3. We all agree on that, code comments should just follow the style guide. Are there places it doesn't? If so I'm happy to open a PR addressing it.

There are places where we intentionally don't follow the code style guide. Specifically as I said above " comments on the same line for results and some short explanations/clarifications." This already has consensus as an approved divergence from the code style guide.

[arthurvr]

Agreed on that. You feel like (1) should be discussed more or can we go and close down this issue?

[scottgonzalez]

It seems like since I've posted that, we've gotten consensus. I've linked to this issue from the main issue for the prose style guide.