Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 
        
Home       Members    Calendar    Who's On


Add to briefcase 123»»»

Author Guidelines Expand / Collapse
Author
Message
Posted Friday, May 14, 2010 3:32 PM
SSChampion

SSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampionSSChampion

Group: General Forum Members
Last Login: Friday, May 18, 2007 3:36 PM
Points: 10,039, Visits: 1
Comments posted to this topic are about the item Author Guidelines
Post #922345
Posted Friday, May 14, 2010 8:57 PM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: General Forum Members
Last Login: Today @ 9:34 AM
Points: 35,532, Visits: 32,115
Here are a couple of more tips about things that either I use or that aggravate the heck out of me...

1. While it’s ok to write articles about things that have already been done (almost everything HAS been done in SQL Server), DO NOT PLAGARIZE! Do your own research, your own work, and your own writing. In those cases where you must make heavy reference to an existing article or other source, make sure you acknowledge those sources either as proper footnotes or as embedded text.

2. DO write an "Introduction" that talks a little about what the purpose of the article is and, maybe, what someone will learn by reading it. Every article should have a goal and it should be gently introduced in the "Introduction". That's why they call it an "Introduction".

3. While it's certainly OK to make a "pretty" article with pretty pictures and screen shots, make sure that any and all code is either in a code block that can be easily copied or included as a "resource" near the end of the article as an attachment. If you include the code as an attachment to the article, you really should let people know about it as a parenthetical comment in the Introduction.

4. When I first started writing, I made the mistake of using the site editor to do the writing with. Don't do that. Do the writing in a decent word processor with a spelling and grammar checker especially if your first language isn't English (actually, English speaking people seem to have a real problem with the language, as well ). Transfer the text and graphics to the site editor only when you're done writing. If you make any changes, make sure you spell check them in the word processor you're using and make sure that you test any code changes.

5. Import all graphics into the word processing document to make sure that they can be imported and that they make sense according to the nearby text. I recommend that all graphics (unless just decorative) have a figure number so that you can easily refer to them in the body of your document.

6. There are very few articles on this site that don’t contain code. Code is what it’s all about and you really need to put your best foot forward. Properly written code can make up for a wealth of sins in the text. The code should be nicely formatted and shouldn’t contain super long lines. It should be properly indented. It should be appropriately commented with, perhaps, a small header explaining its purpose in life, as well. It should be consistent in format. For example, if it’s your style to capitalize all SQL Server keywords, then make sure they’re ALL capitalized. If it’s your style to make mixed case variables and column names, then make sure they’re ALL mixed case.

7. You should have test data available for your code examples. If the test data uses something available to everyone such as the “AdventureWorks” database that comes with SQL Server, then no problem. Otherwise, you’ll need to provide test/demo data and it should be in a “readily consumable” format which includes the CREATE TABLE statement and INSERT, SELECT/INTO, or INSERT/SELECT statements to create the data. For increased credibility especially in performance related articles, I strongly recommend you learn how to build large volumes of test data without using a While Loop or other forms of RBAR.

8. Do not ever claim any type of performance gain or efficiency in your code unless you prove it in the article with LOTS of test data and have tallied the results. Otherwise, people WILL eat you alive especially if you’re wrong.

9. This site supports all versions of SQL Server. If a particular version of SQL Server is required to support the code in your article, then identify what that version is as a courtesy to your readers.

10. Name your article after what the article talks about. While that may seem obvious, too many people try to get clever with article names making it difficult to find in the archives or with Google. For example, if your article is mostly about how to make hierarchical tree structures using Nested Sets, don't call it something like "Going Ape in the Bushes". That's a nice little splash but no one will ever find the article again. Instead, call it something like "Building the Nested Set Hierarchical Model". One of the best ways to name an article is to ask yourself, "What would my Google search be if I wanted to actually find this article."

11. Last but not least, any code you post DOES ACTUALLY HAVE TO WORK or people will think you’re an idiot. TEST, TEST, TEST!

Writing is a heck of a lot of fun and isn’t really difficult at all. Have fun at it. You don’t need to be a professional writer to write articles for SQLServerCentral.com. Just remember that your work is being published on the Internet with a possible viewing audience of millions one of whom may be your next boss . Even though you may not be a professional writer and whether you write in a professional style or a “Developer-to-Developer” style, always put your best foot forward.


--Jeff Moden
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #922406
Posted Tuesday, May 18, 2010 12:48 PM


SSCertifiable

SSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiable

Group: General Forum Members
Last Login: Yesterday @ 12:00 PM
Points: 7,847, Visits: 9,596
Nice guidelines up to a point. There something rather bizarre though: the claim that "following" is not a noun and therefor can't begin a sentence is pure nonsense. It's actually the kind of error that irritates me intensely. Words like "following" have two functions in English: to act as present participles, ie as a particular kind of adjective, and to act as gerunds, ie as a particular kind of noun.

Following the rules of English grammar leads inevitably to the conclusion that that all gerunds are nouns, including "following". If you want to avoid people writing things where "following" is used as a noun but not as a gerund (for example "The following is another way of achieving the same result.") just say that, and don't pretend that the use of "following" as a noun is not perfectly good English, since using it as a gerund (a verbal noun) is perfectly correct English as the first sentence in this paragraph demonstrates. If instead you want to ban all sentences which use "following" as a noun I guess that's up to you, they are your rules/guidelines, but don't appeal to the imaginary nonexistence of the noun "following" to justify it - because they are your rules you don't have to justify it at all, so why give a nonsense justification? If you feel you must justify this rule, you could say (as you have elesewhere) "don't do it because most of you get it wrong".

I suspect that your apparent view that use of "following" as a noun in the italicised sentence above is not generally accepted as good English usage is a bit out of date, but I wouldn't complain about that because my some of my own views on English usage are probably a bit out of date too. And of course these things are sometimes different on different sides of the pond.


Tom
Post #923832
Posted Wednesday, May 19, 2010 8:46 AM


Mr or Mrs. 500

Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500Mr or Mrs. 500

Group: General Forum Members
Last Login: Thursday, September 5, 2013 2:13 PM
Points: 556, Visits: 4,099
Ah, the fun issues with English grammar (on both sides of the pond. ). The one thing that makes this language so interesting and so strong but also a major pain in the brain, all the rules and exceptions to those rules. Or, as I like to put it, there is only one rule in English: There is an exception to every rule.

For those who want to put a bit of polish on their articles or have questions about English Grammar and styles, I recommend The Chicago Manual of Style. This is a publishing industry standard and it has very good explanations of the rules of English grammar and the styles that have been created over the years. There are other style manuals out there that are just as good, this one is just my personal favorite and the one I am most exposed to.

One of the things mentioned in The Chicago Manual of Style is that the rules discussed in the book are not set in stone. You can follow them or not. Following that statement in the book is the advice to be consistent in your style choices throughout the piece. It makes the article easier to read.

Basic rules of grammar need to be adhered to so your article can be read and understood. It is those rules (like the agreement of the subject with the conjugation of the verb, the use of articles, etc.) that allow your ideas and comments to be communicated and duplicated by your readers. If you are not quite sure of them, get someone who is fluent in English to read over your article and suggest corrections. Some things might be typos that a spellchecker will not catch (like "too be" when it should be "to be") but others might be just plain wrong, "I are watching" is something the spell checker won't pick up, a grammar checker might, but someone fluent in English will spot immediately.

Of all the advice in the article and following posts, getting someone to review it for grammar errors is at the top of the list. While the code in your article really does need to work, if your grammar is lousy, people aren't even going to get to your code. Good grammar in the articles allows you to get to first base. The other tips and guidelines allow you to make it back to home base with a successful article.


-- Kit
Post #924361
Posted Sunday, May 23, 2010 10:09 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: General Forum Members
Last Login: Today @ 9:34 AM
Points: 35,532, Visits: 32,115
All that being said, I can tolerate grammatical errors (especially since I make them all time ) unless they make the article virtually unreadable. I AM mostly interested in the code and the idea behind the code. I certainly understand that these articles are written by folks (heh... like me) whom I know are not professional writters. (Should I have used "who" or "whom" or "that" there? )

The big thing for me is that if the only bad thing anyone has to say about a given article is about grammatical errors, then who ever (or is that "whom ever"? ) wrote the article did a pretty good job.


--Jeff Moden
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #926523
Posted Thursday, May 26, 2011 6:43 AM


Right there with Babe

Right there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with BabeRight there with Babe

Group: General Forum Members
Last Login: Today @ 12:09 PM
Points: 717, Visits: 3,033
Tom.Thomson (5/18/2010)
Nice guidelines up to a point. There something rather bizarre though: the claim that "following" is not a noun and therefor can't begin a sentence is pure nonsense. It's actually the kind of error that irritates me intensely. Words like "following" have two functions in English: to act as present participles, ie as a particular kind of adjective, and to act as gerunds, ie as a particular kind of noun.

Following the rules of English grammar leads inevitably to the conclusion that that all gerunds are nouns, including "following". If you want to avoid people writing things where "following" is used as a noun but not as a gerund (for example "The following is another way of achieving the same result.") just say that, and don't pretend that the use of "following" as a noun is not perfectly good English, since using it as a gerund (a verbal noun) is perfectly correct English as the first sentence in this paragraph demonstrates. If instead you want to ban all sentences which use "following" as a noun I guess that's up to you, they are your rules/guidelines, but don't appeal to the imaginary nonexistence of the noun "following" to justify it - because they are your rules you don't have to justify it at all, so why give a nonsense justification? If you feel you must justify this rule, you could say (as you have elesewhere) "don't do it because most of you get it wrong".

I suspect that your apparent view that use of "following" as a noun in the italicised sentence above is not generally accepted as good English usage is a bit out of date, but I wouldn't complain about that because my some of my own views on English usage are probably a bit out of date too. And of course these things are sometimes different on different sides of the pond.

Tom, it's a sparkling pleasure to read an exposition on grammar -- with the word "gerund" no less! -- from a technology expert. I couldn't agree more with you: declaration of personal preference is not the same as a violation of The Globally Enforceable Rules of English Grammar (copyright Megadodo Publications, Ursa Minor Beta).

Yours,
Rich
Post #1115408
Posted Friday, June 24, 2011 7:57 PM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Sunday, October 21, 2012 4:56 PM
Points: 4, Visits: 42
I understand that you need to have certain rules and make them available for the folks who want to publish here. Also I understand that the basic rules of English grammar should apply. However, if you took the liberty to write about the rules, be consistent.
It is a bad English, to use the same word in two consecutive sentences. For example: "We have a series of styles and formatting options available to you, however these are not necessarily everything you may want. However, please use the styles that are available in the editor for most of your work."
Another thing that looked odd to me was in the very next sentence: "If you have not published an article, we will not grant exceptions, so stick with that is available." Wouldn't it be right to say it like this:"If you have not published an article, we will not grant exceptions, so stick with what is available?"
So, please, could you learn English first, and then look from your unreachable heights down at the people who try to publish here ?
Post #1131551
Posted Saturday, June 25, 2011 12:19 AM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: General Forum Members
Last Login: Today @ 9:34 AM
Points: 35,532, Visits: 32,115
ark.trofman (6/24/2011)

So, please, could you learn English first, and then look from your unreachable heights down at the people who try to publish here ?


You were doing fine right up to the point where you wrote that. The ad hominem attack and the sarcasm is just not necessary to get your point across. I strongly suggest that, before you admonish anyone for their grammatical errors, you first learn some manners.


--Jeff Moden
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #1131570
Posted Saturday, June 25, 2011 2:09 AM


SSCommitted

SSCommittedSSCommittedSSCommittedSSCommittedSSCommittedSSCommittedSSCommittedSSCommitted

Group: General Forum Members
Last Login: Today @ 9:44 AM
Points: 1,806, Visits: 5,861
I think standards are important, but this section made me giggle :
You get one and in a sentence. If you have more than that, or have an "or" or "but", you need two sentences. It's hard to make this read well and most people can't do it.


Fine example


MM


  • MMGrid Addin
  • MMNose Addin


  • Forum Etiquette: How to post Reporting Services problems
  • Forum Etiquette: How to post data/code on a forum to get the best help - by Jeff Moden
  • How to Post Performance Problems - by Gail Shaw

  • Post #1131588
    Posted Saturday, June 25, 2011 6:25 AM
    Forum Newbie

    Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

    Group: General Forum Members
    Last Login: Sunday, October 21, 2012 4:56 PM
    Points: 4, Visits: 42
    Jeff Moden (6/25/2011)
    ark.trofman (6/24/2011)

    So, please, could you learn English first, and then look from your unreachable heights down at the people who try to publish here ?


    You were doing fine right up to the point where you wrote that. The ad hominem attack and the sarcasm is just not necessary to get your point across. I strongly suggest that, before you admonish anyone for their grammatical errors, you first learn some manners.


    My manners simply reflect the overall tone of the article on Author Guidelines - nothing more, nothing less. I understand that they have a great deal of articles and wrote guidelines based on the material they getting. However, it is not necessary to ridicule the current and prospective correspondents in such an article. As a matter of fact, there is no necessity for this at all.
    Post #1131616
    « Prev Topic | Next Topic »

    Add to briefcase 123»»»

    Permissions Expand / Collapse