How to Format Articles for DZone

Our editing staff is ready to lend a hand to make your articles shine. But if you want to save time and see your article published sooner, here's how to send them in.

We often get posts that cover completely relevant topics and adhere perfectly to our article submission guidelines. The challenge is that we'll get posts that require some heavy formatting work, and that alone can add a lot of time to some already cramped schedules. With that in mind, I'm going to cover some basic guidelines to consider when submitting articles to the site. The chief benefit is that the closer an article is to perfect when we get it, the sooner it gets through our moderation queue.

Given just how long this post might end up being, here's a quick table of contents so you can scroll to the section that might be of use to you:

• Headers/Headlines
• Body Text
• Our Toolbar
• The Tools We Use

Headers

We follow some basic SEO protocols in our work. That means using our article headlines as H1s (that's automatic, don't worry about it) and working our way down the hierarchy. Sections in articles, like the one for this here, should be H2s. Subsections for those are H3s, and their subsections are H4s. For instance...

Subsection Headers

See? H3.

H4 Headers

And now it's H4.

How to Change Headers

Don't see how to swap headers around? I'll show you. First, select the paragraph or headline you want to change. You can either just click on a spot within the HTML element you want to change, or you can highlight the whole thing. Using the toolbar at the top of your article, click on the text selector, the very first button on the left:

Up pops options for header sizes, normal text, and block quotes. Just pick what you want to use, and the site will make the change for you.

Capitalization

As you might have noticed, the Subsection Headers section had both words capitalized. We use Associated Press (AP) style for capitalization of headers and headlines. That means that the first word in a headline, the last word in a headline, any words four characters long or longer, and all verbs should be capitalized. Or, instead of remembering all that, you can use this site. Cheater.

Body Text

Technically, we use the Microsoft Manual of Style in our work. It's similar to AP style, so if you know either, you're basically in the clear. If you don't know either of them, here are a few basic tips.

Oxford Commas/Serial Commas

This is where we break from AP style. We love the Oxford comma at DZone. If you haven't heard of the Oxford comma, also known as the serial comma, it's this little thing in this sample sentence: "My favorite programming languages are Java, C#, and Python."

It's the comma between C# and Python that's bolded and italicized. AP style doesn't use them, but we do.

American Spelling

The fact that I didn't spell "favorite" as "favourite" in my sample sentence in the previous section should probably have tipped you off, but we favor (rather than favour) American spellings. That's not a slight against our European readers and writers — it's as simple as the fact that we're based in America and it's how we spell words. 

Our Toolbar

Of course, text is only part of your article. There are additions like code blocks, code snippets, images, and movies that you can add to posts to make them really shine. I'll give you a rundown of how to handle those add-ons now.

Code Blocks and Snippets

So, if you're like most devs, you probably know a programming language or two. Or six. Or 20. Anyway, if you're writing about code, it's probably a good idea to put it on display. Let's use a couple of easy examples.

Say you're writing an article about Optionals in Java. If you just want to highlight the word Optional in-line in a sentence, that's pretty easy. For short bits like that, you can highlight it, then go up to our content management system’s menu bar, then click the button that looks like “</>”, as seen highlighted below:

Pick "Code Snippet," and your highlighted word will appear just like it did in the previous paragraph. See? Optional. As a side note, our editor likes to add extra spaces on either side of whatever gets turned into a code snippet. It helps break it up from the rest of the string/sentence in most cases, but be aware that there might be a space or two you should quickly delete.

Code blocks are just as easy, and there are two ways you can handle them.

Method 1

Method #1 is for when you already have code in an article, it just is to do the same thing as code snippets. Let's start with this sample bit of code:

public static <T> Optional<T> empty()

Highlight it, then pick the code tool from the toolbar. This time, though, from the dropdown menu, choose "Code Block," as seen below:

This time, you'll get a pop-up:

Make sure to pick the language you're working with in the box above the code. If you click in that box and start typing, you'll see plenty of other options. Here's what we have in the SQL realm, for instance.

Anyway, once you've got your code in and your language picked, just hit the big green "Save" button, and you should be left with:

public static <T> Optional<T> empty()

Method 2

Method #2 is for if you're not turning text into code. If you're starting with a blank slate, you can just open up the Code Block pop-up:

Then you can either type in your code or just copy it over and paste it in. Pick your language, hit save, and you'll be all set.

Images

Inserting images is easy. Start with the Insert Image tool on the toolbar. Click on it, and you'll have a few options:

You can either drag and drop an image, click on the gray box (where it says "or click") and open a browser to choose your image, or you can just enter the image URL, if it's online.

As for formatting, we generally have two guidelines. The first is that we like most images to be standalone, as in not in-line. That's not always true, but it often is. To do that, click on an image, then click on the far-left icon on the toolbar that pops up.

Second, most images are centered in our text. Again, that's not always true, but it's usually true. To do that, again, click on the image. Then click the alignment tool, the second one on the left:

Click the "centered" option, and presto: All done.

Videos

Now we get to videos. Videos are a great way to share presentations or host tutorials, and adding them is generally pretty easy. Like Spring Boot? If so, you've probably seen this video tutorial on DZone.

To put videos into articles, all you need is the embed code (or a YouTube URL). Open the Insert Video Tool, then choose how you want to import it (via embed code or YouTube URL). Paste the proper text into the proper box, and you're all set.

So this:

Becomes:

The Tools We Use (And You Can, Too!)

We also use a couple of tools to make our lives easier. They're also great for writers to have at the ready because they solve a lot of problems before they start.

Grammarly

If you haven't heard of or used Grammarly, you probably want to familiarize yourself with it. Grammarly is a fantastic tool for checking for spelling and grammar errors. When editing dozens upon dozens of articles a week, it's a lifesaver for catching mistakes that might otherwise go unnoticed. For example, let's go back 30 seconds in time to the subsection on American spellings.

Those red underlines are Grammarly's way of saying, "Hey, I think something's wrong here!" In this case, Grammarly is asking me if I forgot how to write in my native language. It's not always right because it doesn't always parse sentences correctly, but it's usually at least worth a look.

Sublime Text

Sublime Text is a tool we use to make big, sweeping changes to text. We usually pull it out when someone imports an article with odd formatting artifacts — usually when the HTML of a blog or a Google doc overrides our own native formatting.

You'll need to know a bit of RegEx, but something like replacing  style(.*?)> (note the space before the word style there; it's important) with > will get rid of all the random style tags that crop up to make life difficult when migrating articles. That will also turn any mention of the word "style" in your text into a greater-than symbol (>), but you can avoid that with a bit of forethought — say, misspelling "style" until you make the changes, then fixing the misspelling. There's probably a better way to do that, though. Let me know in the comments!

Parting Thoughts

Those are the basics of how we style articles on DZone. I hoped they helped shed some light on how we do things around here! Feel free to use all, some, or none of the suggestions I put forward. They're just here to be helpful. Just keep in mind that the better formatted your articles are when we get them, the faster they'll get through moderation. Also, if you have questions, feel free to leave a comment, and we'll answer them if we can (or forward them to the appropriate party if we can't).

Additional Resources

How to Submit a Post to DZone

What Is Plagiarism? How to Avoid It and Cite Sources

Turning a Press Release Into a Tutorial

SEO Writing 101 Guide