Opensource.com style guide | Opensource.com
Opensource.com style guide
To get started writing for us, please review and follow our style guide for articles.
We encourage users of open source technology and subject matter experts to submit an article idea or draft for review. Learn more about how to be a part of our community, and find out what our authors say about writing.
All content is licensed under a Creative Commons BY-SA license unless otherwise noted.
- Open source license requirements
- Grammar and spelling
- Word count
- Formatting text
- Submission guidelines
- Tips for promoting your Opensource.com article
Opensource.com accepts articles about software, hardware, and other open source-related topics. Regarding software, hardware, and design, the projects or tools must hold certain licenses to be publishable on the site.
There's a lot of information on the internet that's free to download but that doesn't necessarily mean it's open source. To ensure you're writing about open source, please review the list of resources below. If you have any questions, contact us.
See more information on how to choose and use licenses in the additional information section.
Hardware (includes design)
Information (content and data)
To search for the license
- Find the repo (GitHub, GitLab, etc)
- Look for the license file, usually called “LICENSE” or "COPYING"
- View the license and verify that it's an OSI license or an FSF-approved license.
- Use a search engine: Enter the "project name"
Some projects may not be on GitHub or GitLab or even in a Git repository, but they can still be open source software (Apache.org, Linux Foundation, and Google projects, for instance, often host their own software).
Dual-licensing is acceptable as long as there is an option for an open source license. Articles must make special note of the different licenses available, and should not cover features unavailable to the open source version.
Learn more about:
- the difference between Creative Commons and Public Domain
- how to share hardware files
- how to provide and use open data via Open Data Commons
- how to use Creative Commons with data
The readers of Opensource.com are technical and non-technical. Many are open source and/or Linux enthusiasts and users. They come from many different backgrounds and fields of study. We welcome all to learn more about open source! To that end, please:
- Include links to open source projects mentioned in your article or to a Wikipedia page describing the project. Ensure these links are valid and legitimate.
- Explain or link to relevant open source licenses, organizations, standards, etc.
- Include links to technical ideas and terms that may not be known by a non-technical audience.
Our editorial team gives each article a thorough copy edit for grammar, spelling, formatting, style, and more. The process is expedited when authors make an effort to proofread and apply proper grammar and spelling to article drafts.
We don't worry too much about word count, and neither should you. If having a word count helps you structure your writing, here are a few guidelines:
500-600 words: Around 500 words might be all you need to provide a project update, announce a new conference, or share other timely open source news.
Example: Tomb Raider coming to Linux, Vulkan support added Wine, and more gaming news (~399 words)
600-800 words: For reference, a 1-2 page print magazine article is around 750 words (1 page without images, 2 pages if it includes several images and/or screenshots). This is a good range for a regular feature article, column submission, interview, or roundup. Consider adding a sub-head or two to break up the text and walk readers through sections of the article.
2 free desktop recording tools to try: SimpleScreenRecorder and Kazam (~639 words)
5 open source home automation tools (~888 words)
800-1,300 words: How-tos, getting-started guides, tutorials, and more thorough roundups that go a little more in-depth tend to be longer than feature articles.
Top 11 project management tools for 2016 (~1,286 words)
10 tips for making your documentation crystal clear (1,041 words)
1,300+ words: If your article is much longer than 1,300 words (e.g., closer to 2,000), we might consider breaking the story up into multiple parts.
Examples of a two-part series:
- When selling a site means selling a community (Part 1: ~963 words)
- Still reeling, SourceForge looks to the future (Part 2: ~1,774 words)
Subheads: If your article is longer than 500 words, consider adding subheads to break up the text and make your article easier to read. Use <h2> and/or <h3> headers. If your article is longer than 1,300 words, we might consider breaking the article into a longer series.
Interviews: Use bold for the questions and regular formatting for the answers.
Inline formatting: We allow italics and bolding, but please use these sparingly. Although using dashes (--like these) is common, we only use mdash characters (—like this).
Code formatting: If your article contains code, please delineate it with the <code> tag and our editorial team will confirm the proper formatting before publication. If it's a short piece of code, the name of the function, or some other small snippet, feel free to leave it in-line within a paragraph, but longer chunks should be broken onto new lines. Do not use blockquotes or the <pre> tag for code samples.
Avoid using phrases like "in the code below" or "in the code above", because layout is never guaranteed. Instead, use a consistent pattern: introduce a block of code by identifying what it does, and then show the reader the code. You may explain more about the code sample afterwards, but if there's another code sample after that, you should clearly introduce it. By following this pattern, you help readers stay clear about what each code sample does, and you avoid confusion about what code is being referred to.
Tables: HTML tables don't resize to fit screens, making them difficult to read on mobile devices. Use bullet lists instead.
Hyperlinks: When linking to an outside source within your article, choose the option to open the link in a new tab with the target="_blank" attribute.
Lead images: Lead images are added to every article that is published on Opensource.com by the editorial team. If you would like to suggest a lead image to be used instead, please let us know. If the editors agree that the image is a good fit, please send image attribution and licensing details.
Inline images: Inline images and screenshots add visual interest, may help to illustrate your article, and break up the text. If you include images, be sure that they match the license being used for your article (our default is Creative Commons BY-SA 4.0), or let us know what the license is and that you otherwise have appropriate permission to share them on our site.
- Attribution: Please include image credits and license details when you submit your draft and images.
- Format: Please submit images as files, attached to your email. Images should not be placed inside the draft.
- Size: Images should be no wider than our column width, which is 600 pixels wide. We strongly encourage you to sample your images to this size before submitting them to ensure they appear as you expect and text is legible. If you need to include a larger image, create a thumbnail and link it to a larger version of the image. Images that appear in Opensource.com articles need to be hosted on our web server to ensure they are visible in perpetuity.
- Label images: Label images so editors can easily tell where each image should be used within an article (e.g., mylinux.png).
- Add captions (if applicable): Be sure to reference within your article text where your image should go and what the caption should read. (e.g., [mylinux.png] Caption: This is a screenshot of my Linux desktop.)
Our editorial team does not require many specifics, but we do strive for correctness and consistency. Here are our main uses:
- serial commas (i.e. cat, dog, and mouse)
- write out numbers below 10 (i.e. nine, eight, and seven)
- format dates as December 1, 2014 (not December 1st, 2014)
- place periods and commas inside quotation marks (except in code samples)
- capitalize the first letter of Opensource.com
- lowercase and use the term open source (do not use Open Source, opensource, or open-source)
If your article (or a version of your article) has already been published on another site, please let us know. Generally, we publish original articles, but we will consider reprinting articles or running a revised version. In any case, we'll want to know upfront whether your submission has or will also appear elsewhere.
The readers of Opensource.com tend to be open source, Linux enthusiasts, and users, and thus computer-savvy; however, readers come from many different backgrounds and fields of study. And, because our mission is to educate readers on a variety of topics as they relate to open source, we:
- Include links to open source projects mentioned in the article, or to a Wikipedia page describing the project at its first mention
- Explain or link to other open source licenses, organizations, standards, etc.
- Include links to technical ideas and terms that may not be known by a non-technical audience
- Spell out acronyms the first time they are used [e.g., Red Hat Enterprise Linux (RHEL)]
We accept articles in a variety of formats: .odt, .txt, .docx, .html, Docbook, or .md file attachment. If you submit a link to an Etherpad or Google document, do not revise the document after you submit it. We will download and edit the draft, so we won't see your changes.
Save all images as files and attach to your submission email. Use descriptive terms when naming your images, and include the name in the article draft where you want the image places. Finally, along with the files, send image attribution information for EACH file: who is the photo by and what is the license?
Send your draft to email@example.com. Include the license for your work (our default is Creative Commons BY-SA 4.0) and your username for your Opensource.com account. (To register for an account, fill out this form. Be sure to add a bio and photo, then save.)
The editorial team will review your submission and respond with next steps.
If your submission is approved for publication, revisions may be requested. The editorial team will make copy edits and more in-depth suggestions if needed. Typically we publish articles within 2-3 weeks after the final revision is approved by the author.
Licensing: We publish content on our site under a Creative Commons BY-SA license. We will consider other licensing options on a case-by-case basis.
Links: All links are subject to the approval of the Opensource.com editorial team. If the primary purpose of your submission is to provide a backlink to your company or product, we are not the right publication for your article. We focus on stories about open source projects, technologies, and communities, not products. Although a product pitch is not a good fit for us, there may be a great story about how you're using or giving back to open source at your organization that we'd love to help you tell.
We strive to publish articles in a timely manner after they are reviewed, edited, and prepared for publication by our editorial team, while also managing our calendar and maintaining a steady cadence. If it is important to you that an article is published by or on a certain date, or if it contains information under embargo until a certain date, please share this with the editorial team during your initial communication.
Check out these tips for promoting your Opensource.com article.