Tips for article style, grammar, content, and SEO

Don’t mix monospace fonts with proportional fonts in a sentence. Use italics for the special text. For instance, don’t write dnf install foo in the middle of a sentence, write dnf install foo.

Use italics for system objects you mention in a sentence:

Use the Preformatted style in the WordPress editor for command line input or output. Use a shell prompt ($ or #) only where it genuinely affects the meaning, or to set the input apart from output. It also helps to use boldface for the input itself:

$ command arg1 arg2
output line 1
output line 2

Use boldface only for an extremely important phrase or statement.

Use sentence case for the post title and heading titles. Don’t capitalize words in your article title or any heading, other than proper nouns. This avoids needless arguments about title case, which differs by region.

Check spelling and grammar. Nobody likes nitpicky comments about this. Check your work before you send it to an editor. Editors: double-check all the work, that’s your job!

Write clearly and use shorter sentences. Brevity is good. Clarity is better. Don’t be excessively wordy when avoidable. If a longer sentence is easier to read, use the extra words.

Avoid passive voice. Passive voice is the use of the object of a sentence as the subject. For example:

Be careful of gerunds (-ing words). They usually indicate passive voice. Rewrite your sentence to make it stronger. For example:

Avoid unnecessary future tense. Unless you’re actually talking about future plans or publications, present tense is best.

Avoid too much use of the verb to be in sentences. Too much use of is, will be, or can be makes your sentences weak and flabby. Try using the verb form of words you’ve shuffled off elsewhere in the sentence. Often you can simply drop words, or use the imperative (commanding or advising) form of the sentence.

Use standard US English for spelling and other international differences. US English is the lingua franca for the Fedora Project overall.

Have a smooth flow from general information to specific instructions. If you’re not sure how to structure your article like this, check out our starter template.

Leave packaged files alone. Processes should not involve editing files under system folders like /usr or /lib*. Edit /etc or a user-specific configuration in the home directory.

Prefer free software where practical (and officially packaged software wherever possible). The Magazine can still cover non-FOSS software to be used on Fedora, where we know or suspect that software is very popular and useful to Fedora users. (Google Chrome is a good example.) But if your article is covering a general process, use FOSS software.

Use libvirt/KVM in tips, not VirtualBox or other hypervisors. Frequently people coming from other platforms have VirtualBox experience. However, the KVM hypervisor and libvirt in Fedora are FOSS and part of the platform. Use them, write about them, love them.

Unless necessary, use Fedora family distributions. The Fedora Magazine promotes Fedora. Unless the point of your article is to specifically explain a cross-distribution mechanism, use installations, containers, or distributions within its family (Fedora, CentOS, RHEL).

Copr software must be accompanied by a caveat. The Copr build system is not managed by the Fedora release team and does not provide official software builds. If you cover some software from Copr, ensure there’s no official build. If not, include a statement like this: Copr is not officially supported by Fedora infrastructure. Use packages at your own risk.

Avoid exclusionary or problematic language. These are examples of terminology to avoid wherever possible in articles:

Test your process. If possible, use a fresh guest VM — or at least a brand-new user account. Run your process from beginning to end to ensure it works. Fix, rinse, and repeat.

Use the correct style for third parties. Names of companies, projects, and technologies don’t always follow the style rules of typical English words. Choose the styling used by authoritiative websites when you’re unsure. If authoritaive sources use inconsistent style, use your best judgment. A non-exhaustive list:

Use a fresh, standard Fedora Workstation, not your personal desktop or setup. (It’s best to make a VM with a fresh Fedora Workstation install, and do the steps there.) If you’re showing something that relies on another desktop, do a fresh installation and use that.

Set screen resolution at a reasonable but not too high resolution, such as 1280x960 or 1280x800.

If you’re only showing a browser window, make it fairly large on the screen and screenshot only the browser. (Hint: you can use the Screenshot app for this!)

If you’re only showing an application, use the default size of the app to screenshot it.

Upload and use that original media in your article. If the shot is large, like a large browser window, app, or whole screen, choose a medium size thumbnail and let WordPress handle the conversion.

Use a simple, relevant title. Preferably this should be a call to action, like Build a widget using GTK+, or a list description, like 5 fun games in Fedora. The title affects search engines, and leads to more hits and higher page ranking. That helps drive traffic to the Magazine.

Provide a featured image. Look at the information here for tips on featured images. You can also feel free to ask the editors to assign this for you. If you make your own image, try to match the style of other images. Use the assets provided in the featured image guide. Don’t add your own fonts or deviate from the guide.

Use good SEO practices. Use the SEO plugin provided to maximize the search ranking of the article. Aim for a “green” rating in the Publish box at top right of your article’s edit screen. Follow these guidelines:

Use the Edit as HTML option when pasting into preformatted blocks. Current versions of WordPress are known to strip leading hash marks (#) and leading whitespace when content is pasted into preformatted blocks. Some non-alphanumeric characters may also get garbled (&, <, >, etc.). Using the Edit as HTML option (listed under the vertical ellipsis) prior to pasting content into the block seems to workaround this problem. Be sure to paste your content between the <pre> tags and do not overwrite them. After pasting your content, switch back to visual mode by using the Edit visually option to see a better representation of what the final result will look like to the reader.