First off, thank you for considering contributing to Codebulbs. It's people like you that make Codebulbs such a great community and the platform where thousands of people learn something new every day!
In this style guide, we’ll give you tips for how you can maximize your impact by making your articles as strong as possible.
This is not a place for “blog-a-day”-style challenges or stream-of-consciousness observational posts.
Bring your facts. Bring your quotes. Bring your code snippets. Bring your data visualizations.
Years of data show that the more in-depth an article is, the longer people will spend reading it, and the more likely they will share it with their friends.
If you’re not able to write at least 1,000 words about your topic, try doing some more research on it first.
By diving deeper and expanding upon your research, you’ll be able to deliver more insight to your readers.
People are busy. So you have to capture their attention immediately. How do you do that? With a compelling headline.
Headlines: The only part of your article that 100% of people will read
Before you start writing your story, spend time crafting a compelling headline. Your entire article will then spring forth from that headline and hook back in to support it.
We’ve found two archetypes that do well: deep technical articles and personal narratives.
Here are a few headline structures we’ve found that work well for deep technical articles:
- "How to fix…"
- "How to build…"
- “How to [task] with [tool]”
- "How [something] works"
- "The [adjective] guide to…"
- “What is a [noun]? In English, please.”
- “What exactly is [noun]?”
- “Why [something] matters.”
- “Learn [something] in N hours”
- "A history of [something]”
- “The story behind [something]”
And here are a few headlines structures that work well for personal narratives:
- "How I [did something]"
- “I [did something]. Here’s what I learned.”
- “How I went from [something] to [something] in N years”
- “Why I started [something]”
- “I’ll never [something] again. Here’s why.”
- “How I [did something] without [something]”
- "Why I don’t [something] anymore"
Add your Cover Image
Once you’ve chosen your clear, informative headline, add a nice cover image. Click the gear in the top-right corner.
Some contributors create their own cover art for their article. A free site like Canva.com can help you with this process. (Image size should be 1200 x 630 px)
If you don’t have an image, you can add a Creative Commons Zero (no attribution needed) image downloading one from a site like Pexels or Unsplash, saving it, and then uploading it to Ghost.
Please do not hot-link images. Instead, download any images you want to use, then drag them into your article on Ghost. This way Codebulbs can serve the images through our own reliable CDNs (for better performance and accessibility). Please try to keep image sizes under 100KB for fast site loading.
Set Your post URL
You can set your article’s URL directly. We recommend keeping these short and descriptive like “machine-learning-with-pytorch-tutorial” or “from-retail-worker-to-software-developer”.
Choose Your Tags
You can choose one to five tags for your article. Once you've chosen them, just let the editorial team know and we'll add them for you.
These tags will make it easier for readers to discover your articles through search and when browsing tags.
The first tag you choose is the most important, and it will show up above your article, like this:
Please don’t change any of the meta information in the menu. Our publication has sane default values for these.
Tips for writing an article people will actually read
Grammar, spelling, and formatting do matter
It’s easier to read articles that are clear and properly formatted. Here are some tips to make your articles as readable as possible:
- Keep it simple. Use simple, straightforward language whenever possible.
- Use short sentences. Break down longer sentences into shorter ones. This helps people read faster and understand better.
- Use short paragraphs. Break down longer paragraphs into one or two sentence paragraphs. Walls of text will make your readers abandon your article or switch to “skimming” mode.
- Clean up the punctuation. Too many exclamation marks can be distracting!!! Semi-colons are rarely necessary; just use a period instead. And ellipses are... well... usually a bit much.
- Use sub-headings to structure your text. Our publication gives you both large and small heading sizes for your toolkit. Use large headings for main topics, and smaller sub-headings for sections within those topics.
- Don't use excessive bold, italics, or both. Too much text formatting makes it hard to read. Especially if you use both bold and italics together. Use bold and italics separately, and sparingly.
- Remove abbreviations. They make articles harder to understand. Spell out any acronym that isn’t well-known. Turn Latin expressions like “e.g.” into “for example” and “… etc.” into “like ...”
Proof-read your article. Then proof-read it again.
Some contributors write quickly so they can get their ideas down on paper. Other contributors do all their research before they write a single word.
Whatever your writing process, be sure to step away from your article and come back with a fresh pair of eyes.
Read your article over again. Then read it out loud. You'll be amazed at the little errors, misspellings, and awkward phrases you catch.
Add syntax highlighting to your code
You can create a code block by typing three backticks (```), followed by hitting the spacebar.
You can even specify the programming language for which you want syntax highlighting.
For example, typing ```javascript will give you JavaScript syntax highlighting. And we support syntax highlighting for a dozen other popular programming languages as well.
Stay on topic
Your readers’ time is finite. Help your readers to get as much value out of your articles as possible before they have to move on with their lives.
Keep your deep technical articles as step-by-step as possible
- Write a concise introduction that tells readers what they’ll accomplish.
- Use a numbered list like this one to indicate steps.
- Pack in as much detail as you can.
- Close out by reminding readers what they just accomplished.
Tell your personal stories like a novel
Even though your headline will probably give away the ending of your story (“How I went from overnight trucker to software developer in 2 years”), you can still tell it like a novel.
Rather than jumping around through time, start at the beginning and paint a picture of your life before, during, and after your journey.
See if you can frame your story around a central conflict. For example, overcoming:
- immigration challenges
- brutal job interviews
- learning disabilities
- age discrimination
- or just procrastination (the most common challenge)
Conflict is central to narrative. Books and movies are interesting because of the conflict between characters, their environment, and even within themselves.
Write longer comprehensive articles instead of multi-part articles
We’ve observed time and time again that people will not bother reading the second, third, or nth part in a series if they haven’t read all the previous parts.
At the same time, we’ve seen that very long, in-depth articles work surprisingly well. People will bookmark your article or share it on social media so they can come back to it.
When people see that an article is long, they’ll often assume the article is serious and comprehensive. This inspires people to slow down and really spend time reading your article. Many people will even open up their code editor and code along at home.
Keep it as G-rated as possible
The Codebulbs community is mostly adults, but there are some children here as well.
If you’re writing about a topic like sexual harassment, there’s no real way to keep it “G-rated.” But in most circumstances, this is possible.
Try not to use profanity unless it’s in a direct quote, and steer clear of potentially offensive memes.
Finally, if an article seems to violate Codebulbs’s code of conduct, we will immediately delete it. But we will save a copy of it and send it to you for your own records, so that you don’t lose your work.
Use Creative Commons Zero images or images you created yourself
You can include screenshots and other images you've created yourself. But if you don't own the rights to a photo, use a similar image that is Creative Commons Zero instead. These don't require licensing fees or attribution.
Please do not hotlink images. Instead, download any images you want to use in your article, then drag them into Ghost. This way Codebulbs can serve the images through our own reliable CDNs (for better performance and accessibility). And please try to keep image sizes under 1MB.
Some images – such as webcomics – are created with sharing in mind. For these, you can insert the image then say "Image credit: XKCD" with a link to the specific page for the webcomic.
Always Credit Your Sources and Don't Plagiarize
Plagiarism is when someone misrepresents someone else’s writing (or image or code, and so on) as their own. It is a serious offense that gets people fired from jobs and kicked out of schools. And we take it just as seriously on Codebulbs's publication.
Few people have been brazen enough to attempt plagiarism on Codebulbs's publication. But there have been a few of them over the past 6 years. We've caught them, removed their articles, and banned them from our community for life.
Don't worry – you are not going to accidentally plagiarize anything. Plagiarism is an intentional act.
How to properly cite your sources
If you are paraphrasing (or quoting directly) something someone said in another article, video, course, or other medium, you should credit them. This means adding a link to the original source and using pull quote formatting, like this:
"This game is controlled entirely by typing into a command line interface. Because the game is real-time in nature, this can lead to some intense moments of rapidly typing commands as you try to save your drones from danger." (Source: Quincy Larson)
This includes text (or code) taken from official documentation, StackOverflow, GitHub, and all similar resources. If you're copying and pasting something from a source like that, make sure you cite it and link to it.
Always attribute quotes to the people who originally said them. If it’s a multi-line quote, you can use pull quotes like these to break up longer paragraphs:
“When you have wit of your own, it’s a pleasure to credit other people for theirs.”
― Criss Jami
If your code is heavily inspired by (or borrowed from) someone else's code, you should credit them.
Before you publish an article that leans heavily on someone else's work, ask yourself: does my article expand substantially on that person's work? If not, it may not warrant an article.
A final note on using other people's words: it's always better to use your own when you can. So rather than copy/pasting and quoting other sources excessively, try to digest the information and explain it in your own words. It'll help you understand it better, and you won't risk plagiarizing someone else's work.
But if you must quote or borrow from another source, make sure to cite it properly.
Some examples of plagiarism
Here are a couple examples of plagiarism – so, what not to do. The first should be fairly clear (it's copied word for word):
Original text:
Just a quick note before we get started: Instagram's desktop interface and mobile app are quite different. Most people use Instagram on their mobile device (from the Instagram app) because that's where you can actually post photos. (Source: Abbey Rennemeyer)
Plagiarized text:
Ok, everyone ready to learn about Instagram? Let's dive in!
Just a quick note before we get started: Instagram's desktop interface and mobile app are quite different. Most people use Instagram on their mobile device (from the Instagram app) because that's where you can actually post photos.
Now that we have that out of the way, we're ready to go.
As you can see, the plagiarized text is sandwiched between original text. It's tempting to add phrases or paragraphs that someone else has crafted really well. But unless you cite those parts, it's plagiarism.
The second example, below, may not stand out as much. But if you're paraphrasing someone else's words closely, that's still plagiarism.
Original text:
There are many reasons you might want to share photos and videos on Instagram.
Perhaps you're starting a business or launching a product. You might work for a company that wants to have an Instagram presence. Maybe you want to build your personal brand as a photographer, traveler, or artist. Or you just want to share what you're into right now via pictures.
Whatever the reason, Instagram is a great place to share ideas, messaging, and art online. (Source)
Plagiarized text:
There are lots of reasons to share photos and videos on Insta.
Maybe you're starting your own business or launching some product. Maybe you work for an organization who wants to have an Instagram presence. Or maybe you want to create your own brand. Or you just want to show what you're doing now in pictures.
Either way, Instagram is a great place to post those ideas, messages, and art online.
As you can see, the above text is heavily based on the original text. It might change a few words, or leave a few out, but it's clear that the person didn't write it on their own. Again, this is not OK, and would be considered plagiarism.
If you have any questions about what constitutes plagiarism, please do some research and make sure you know how to properly cite your sources and create original work.
No cross-posting, please.
Cross-posting is generally ineffective. If you want a lot of people to read your article, we recommend you publish that article in a single publication – whether that's Codebulbs's publication, or your own blog, or an online magazine.
A couple exceptions to this:
- It can be worth it to cross-post an article within a walled garden (that is not indexed by Google) like LinkedIn and Facebook.
- And if you want to feature your own writing from other publications on your own blog for potential employers to see, you can cross-post onto your own blog and just use a canonical URL to point back to the original publication. This will reduce the likelihood that Google gets confused and shows the wrong version in its results.
You can, however, take some of your personal blog posts on a similar topic (such as "Visual Studios Plugins" or "Advanced Bash Commands") and anthologize them into a single, longer Codebulbs article.
Our philosophy is that since we are going to spend hours coaching you on your article, meticulously editing it, and publicizing it to the broader Codebulbs community, we ask that you not cross-post it on open publishing sites like Medium.
Acceptable ways you can self-promote in your articles
We ask that you keep this as tasteful as possible. It is perfectly fine to have a one-sentence call-to-action for your product at the end of your article.
Don’t open your article with a link to your product, as this looks spammy. And don't use affiliate links in your articles unless they are links to books or courses that you have personally created.
Also note that we do not allow branded accounts. We forbid any sort of ghost writing. And we will not transfer articles from one employee in a company to another.
And please – do not write stories on behalf of other people who have not yet earned their Codebulbs contributor account.
Note that for your own SEO purposes – unlike most popular websites – all links on our publication are rel="doFollow". This means that yes – each page you link to (including your own blog) will get a boost in Google rankings. Please keep this in mind and don't over-do it.
Finishing up the process
Once you’re confident your story is ready for readers, email a link to your draft to [email protected]. Our editorial team will quickly go through and make edits to further strengthen your article before publishing it.
The main things we care about are the headline and the opening paragraphs. If we notice any text formatting issues or grammatical errors, we’ll correct them too.
If we still think your article needs significant work, we will tell you so, and you can then re-submit it once you've made those changes.
Other helpful tips
GitHub Markdown
Did you know you can use GitHub-flavored Markdown to compose your articles?
You can paste markdown into /news and it will be instantly converted to rich text.
You can also type markdown syntax at the beginning of a line - say # or ## for headings, or * for a bulleted list – then start typing. The text will change to your specified format.
Go easy on the embeds
You can embed things like tweets and YouTube videos if you want. Just click the + icon at the beginning of a new line, and you can choose from a variety of embedding tools.
This said, we encourage you to use these sparingly, for three reasons:
- The embeds make a call to an external service, such as Twitter, which may slow down the experience
- Many people who read the publication are doing so using screen readers. A large portion of the developer community lives with visual impairments (or completely blindness). Embeds are less accessible than text.
Thank you for sharing your insights with the developer community.
We hope this guide will help you write better articles so the entire community can benefit from your insight.
Happy coding!
— The Codebulbs Editorial Team
Attribution
This style guide is adapted from freeCodeCamp https://www.freecodecamp.org/news/developer-news-style-guide/
For any inquiries, anyone can contact us at [email protected]
