4

As many of you know, I like editing posts (proof) to try to standardize formatting on this site. It helps to keep this site clean and it improves quality of the posts.

Here are some suggested rules we can follow for formatting posts:

  • Use a capital letter at the beginning of the title, but not for each word in the title
  • Use code formatting for code elements, URLs and email addresses and only code formatting
  • Apply italic style for file paths or file names and only italic style (.htaccess for example)
  • Use blockquote formatting for quotations
  • Apply capital letters for each word in a product name ("Google AdWords" and "Google Webmaster Tools", not "google adwords" or "Google webmaster tools"); if you don't know the right way of writing, please search on Google
  • Apply capital letters to proper nouns such as "English"
  • Use quotation marks around example words such as "another example"
  • Apply formatting rules of English (one space after a period, comma, semi-colon, or question mark, but none before)
  • Use numbered list for list of defined number of elements
  • Use bulleted list for list of undefined number of elements
  • Use punctuation consistently in a list (for example all list elements with no punctuation at the end except for questions)

Please feel free to add or update some rules and share your opinion on those suggestions.

  • So is it robots.txt or robots.txt? It is both a file name and a file path. – Stephen Ostermiller Nov 28 '13 at 11:21
  • 1
    Another one to consider: does punctuation go inside or outside of quotation marks. English style guides usually say inside, but they were written for expressing dialog where the punctuation doesn't change the meaning of what is inside. In the case of technical content (especially examples), putting punctuation inside can be confusing. – Stephen Ostermiller Nov 28 '13 at 11:23
  • The debate over one space or two after the end of sentences is somewhat moot. Even if you use two spaces after a sentence, the rendered post will only display one. The point about no space before most punctuation is a good one. – Stephen Ostermiller Nov 28 '13 at 11:46
  • 1
    Regarding robots.txt, I think we should keep the using of code formatting for code elements and URLs. However, we can use italic style for file names and file paths. For putting punctuation inside, if it can be confusing, maybe you can put it outside. What do you think? – Zistoloen Nov 28 '13 at 12:33
  • 2
    I think what you've posted as been the de facto standard used here and at other Stack Exchange sites. Of course, the problem with standards is newbies don't know them... But having the standards officially documented somewhere is a good thing. I do all of the above except use punctuation at the end of a list item. But I can get over that. – John Conde Nov 28 '13 at 16:09
  • @Stephen: I agree with John, do you think using punctuation at the end of a list is necessary? It appears not logical to me either. – Zistoloen Nov 28 '13 at 21:44
  • I am certainly in favor of consistency. Currenty that the list in the question has some items that have periods and some that don't, while all the items are complete sentences. – Stephen Ostermiller Nov 29 '13 at 10:13
  • Ok for consistency and no punctuation at the end of each element of a list by simplicity. – Zistoloen Nov 29 '13 at 12:01
3

Having a standardized guideline for editing is helpful, however the following things should be considered:

make the post substantively better when you edit, not just change a single character. Tiny, trivial edits are discouraged.

So instead of editing the question for a single guideline list item above, consider if there are also other issues that can be improved, and if not, whether the edit would substantively improve the post on its own.

Ideally, editing should be motivated by recognizing that a post is difficult to read, understand, or is missing necessary detail, and that your edits would help to improve these things for others.

  • Edit in moderation, as this can flood the Home and Active pages, diluting the number of new questions and answers visible to others.

  • It's probably not a good idea to perform minor edits on competing answers, as those might be viewed as an attempt to alter or gain an advantage over them.

  • One possible justification for a minor edit is to remove links or product/service recommendations that appear to be an obvious attempt at self-promotion, in which the post would otherwise be informational; if not, just flag it for moderation.

  • Lastly, this guideline should be easily found by other members (e.g., as a link from the Help Center).

  • Thanks dan for participating. I totally agree with you on these four points. However, for your first point, I agree if the user doesn't have privilege to edit without peer reviewing. A user with edit privilege like you and me (+2000 reputations points), it can be useful to permit minor edits to apply the same formatting for a maximum of questions and answers, it improves the general quality of the site (yes I'm so rigourous :-)). For your second point, a good way would be to mainly edit new questions or answers. – Zistoloen Jan 3 '14 at 17:58
  • Thanks. There's been some rumblings as of late about edits being too minor, hence my answer. Not sure that beautifying the site, or doing so to collect points, should be a goal (i.e., it's not a site on language usage) - unless done en route to improving the quality of the post for others. So the point here is to suggest thinking about if edits are too minor, as discouraged in this and other Stack Exchanges sites, and to understand why they might be rejected if so. – dan Jan 3 '14 at 23:32
  • The biggest criteria for "too minor" in mind mind is that it doesn't fix all the problems in the post. The second would be that it only changes things like white space or emphasis in a way that is arbitrary. Any single change that actually improves the post is fine with me as long as there aren't other problems that were overlooked. – Stephen Ostermiller Jan 15 '14 at 3:45
  • Any single change that makes the post substantively better would meet the standard indicated in the Help Center for this and other Stack Exchange sites. Trivial edits, like just capitalizing commonly known names for example, doesn't really meet that criteria. Applying the above guidelines without any standards could lead to attempts to increase reputation, badges, and recognition on the site, without really improving posts. Minor edits may also make the site appear overly pedantic and turn-off new users. – dan Jan 16 '14 at 6:19
  • This is also why Reviewers have the option for: This edit is too minor; suggested edits should be substantive improvements addressing multiple issues in the post. – dan Jan 16 '14 at 6:20
2

I am in favor of codifying our style guide. I added a couple items to your list and posted comments with questions about others.

  • 1
    Thanks Stephen for participating. – Zistoloen Nov 28 '13 at 12:34

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .