Click here to monitor SSC
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


Author Guidelines


Author Guidelines

Author
Message
Site Owners
Site Owners
SSChampion
SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)

Group: General Forum Members
Points: 10063 Visits: 1
Comments posted to this topic are about the item Author Guidelines
Jeff Moden
Jeff Moden
SSC-Forever
SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)

Group: General Forum Members
Points: 44845 Visits: 39850
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.
Although they tell us that they want it real bad, our primary goal is to ensure that we dont actually give it to them that way.
Although change is inevitable, change for the better is usually not.
Just because you can do something in PowerShell, doesnt mean you should. Wink

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
TomThomson
TomThomson
SSChampion
SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)SSChampion (10K reputation)

Group: General Forum Members
Points: 10650 Visits: 11983
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

Kit G
Kit G
Mr or Mrs. 500
Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)Mr or Mrs. 500 (562 reputation)

Group: General Forum Members
Points: 562 Visits: 4113
Ah, the fun issues with English grammar (on both sides of the pond. :-D). 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
Jeff Moden
Jeff Moden
SSC-Forever
SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)

Group: General Forum Members
Points: 44845 Visits: 39850
All that being said, I can tolerate grammatical errors (especially since I make them all time :-P) 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? :-P)

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"? :heheSmile 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.
Although they tell us that they want it real bad, our primary goal is to ensure that we dont actually give it to them that way.
Although change is inevitable, change for the better is usually not.
Just because you can do something in PowerShell, doesnt mean you should. Wink

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
Rich Mechaber
Rich Mechaber
Ten Centuries
Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)Ten Centuries (1.1K reputation)

Group: General Forum Members
Points: 1085 Visits: 3661
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
ark.trofman
ark.trofman
Forum Newbie
Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)

Group: General Forum Members
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 ?
Jeff Moden
Jeff Moden
SSC-Forever
SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)SSC-Forever (44K reputation)

Group: General Forum Members
Points: 44845 Visits: 39850
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.
Although they tell us that they want it real bad, our primary goal is to ensure that we dont actually give it to them that way.
Although change is inevitable, change for the better is usually not.
Just because you can do something in PowerShell, doesnt mean you should. Wink

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
mister.magoo
mister.magoo
SSCrazy
SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)SSCrazy (2.3K reputation)

Group: General Forum Members
Points: 2266 Visits: 7820
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 :-D

MM


select geometry::STGeomFromWKB(0x0106000000020000000103000000010000000B0000001000000000000840000000000000003DD8CCCCCCCCCC0840000000000000003DD8CCCCCCCCCC08408014AE47E17AFC3F040000000000104000CDCCCCCCCCEC3F9C999999999913408014AE47E17AFC3F9C99999999991340000000000000003D0000000000001440000000000000003D000000000000144000000000000000400400000000001040000000000000F03F100000000000084000000000000000401000000000000840000000000000003D0103000000010000000B000000000000000000143D000000000000003D009E99999999B93F000000000000003D009E99999999B93F8014AE47E17AFC3F400000000000F03F00CDCCCCCCCCEC3FA06666666666FE3F8014AE47E17AFC3FA06666666666FE3F000000000000003D1800000000000040000000000000003D18000000000000400000000000000040400000000000F03F000000000000F03F000000000000143D0000000000000040000000000000143D000000000000003D, 0);




  • 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

  • ark.trofman
    ark.trofman
    Forum Newbie
    Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)Forum Newbie (4 reputation)

    Group: General Forum Members
    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.
    Go


    Permissions

    You can't post new topics.
    You can't post topic replies.
    You can't post new polls.
    You can't post replies to polls.
    You can't edit your own topics.
    You can't delete your own topics.
    You can't edit other topics.
    You can't delete other topics.
    You can't edit your own posts.
    You can't edit other posts.
    You can't delete your own posts.
    You can't delete other posts.
    You can't post events.
    You can't edit your own events.
    You can't edit other events.
    You can't delete your own events.
    You can't delete other events.
    You can't send private messages.
    You can't send emails.
    You can read topics.
    You can't vote in polls.
    You can't upload attachments.
    You can download attachments.
    You can't post HTML code.
    You can't edit HTML code.
    You can't post IFCode.
    You can't post JavaScript.
    You can post emoticons.
    You can't post or upload images.

    Select a forum

































































































































































    SQLServerCentral


    Search