Author writing guidance

Headings and subheadings

In Microsoft Word, please use Heading 1 only for the article title and Heading 2 – 6 for subheadings within the article.

Highlighting names of controls, list items, dialogs/forms or other UI elements

For readability please highlight the name of these items by (title) capitalizing them as they are capitalized themselves and bolding them e.g. Then click Next.

Example:

  1. In the Object Explorer, connect to an instance of the SQL Server Database Engine and then expand that instance
  2. Right-click Databases, and then click Reports
  3. Select Memory Usage By Memory Optimized Objects

This also applies to things like DMVs e.g.

We can also use the related DMV sys.dm_db_xtp_table_memory_stats to draw the sizing details of the memory optimized tables.

Markup

We encourage you to read and implement the suggestions in this article – How to markup, annotate content like a boss.

Categories

Please liberally categorize content.

By adding categories, content can be broken up into more readable chunks and in general better organized.

In some cases, you can make a TOC of the categories at the top of your article.

For categories, please capitalize as Normal content, not Title Content. Here is a good example:

Correct:          Memory consumption by internal system structure components
In-correct:      Memory Consumption by Internal System Structure Components

Showing SQL query results

Screen shots below are appropriate to show results.

SQL or other code

When adding code to your article, just indicate with the comment what language is used.

We support syntax highlighting for the following languages:

If you are posting some other language, please format it in Courier text (for visibility) and include a comment of what the language is. We’ll try to syntax highlight it according to the language specifications.

Please avoid using screenshots of code instead of code itself.

Links

We encourage internal links where authors to cite other articles they have written on SQLShack as references. These cross-links help to introduce readers to other articles you have written.

We also encourage 2-3 external links, references included in the main body of the article to content on other/external websites.

We suggest separating these into their own paragraph, putting in italics and indenting.

Minimum word requirement

We are requesting all authors write at least 1,250 words (not including scripts, code). Current studies show that “more is better” and that, in general, the sweet spot is 1,600 words. But articles that rank in the top 3 tend to be over 2K words. Most of our authors are doing this already.

SEO

You should have a keyword in mind when writing your article. Check with us first, before writing, to get a keyword by sending a proposed topic including:

  1. Title
  2. Brief description
  3. Links to comparable articles

We’ll quickly confirm, if we approve the article and provide a keyword.

Use the keyword as follows:

  1. In the title, as far to the left as possible
  2. In the first 150 chars, as close to the beginning as possible
  3. 1x every 100 words
    Note: You can use ALT tags to help meet this requirement

Images

Resolution

  • Optimal resolution is 1200x600px
  • Minimal width is 400px.
  • In case all images have 400px width, you must provide 1 image with 1200x600px resolution

Borders and shadows

  • Images should not have any borders or shadows around it
  • Images should be properly cropped, without any background content around the edges

Improperly cropped image:

SQL import of compressed data: Execute Process Task Editor

Properly cropped image:

Alt text

  • All images must contain alt text
  • Add alt text in Word: Right-click on the image -> Edit Alt Text

  • If you don’t see this option, you can edit Alt text the other way:

    1. Right click on the image
    2. Click “Format picture …”
    3. Select the image 3rd from the left (2nd from the right) at the top
    4. Select “Alt text”
    5. Enter information in “Description” – not title
    6. The information should be a brief description of the image. I’ve actually been taking out text from the article that describes it and pasting it in
    7. If you need a few more keywords to make sure you have 1 keyword for every 100 words, this is a great way to accomplish that

Put in a description of the image. Length doesn’t really matter.

This presents a great opportunity to get in more keywords to meet 1:100 words. Sometimes if your keyword is awkward, this is a great place to put it to avoid making your article read awkwardly.

SQLShack
Latest posts by SQLShack (see all)