Tips for article style, grammar, content, and SEO

These tips will help your article sail through editing. Be kind to your editor(s), and read this before you start.

Markup

Primary rule: don’t get too fancy. Legibility is important.

  1. 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.

  2. Use italics for system objects you mention in a sentence:

    • GUI or CLI elements like button text or menu entries

    • other prompts the reader must find on the screen

    • commands or package names

  3. 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

  4. Use boldface only for an extremely important phrase or statement.

Grammar and style tips

  1. 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.

    • Incorrect heading: Use Sentence Case for Post Titles in Fedora Magazine

    • Correct heading: Use sentence case for post titles in Fedora Magazine

  2. 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!

  3. 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.

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

    • Active voice: The troops defeated the enemy.

    • Passive voice: The enemy was defeated by the troops.

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

    • Weak, passive voice: Setting the foobar configuration option will make the application listen on all interfaces.

    • Strong, active voice: Set the foobar configuration option to make the application listen on all interfaces.

  6. 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.

    • Weak: Zambone is an app used for managing your private documents on a server.

    • Strong: Zambone manages your private documents on a server. Or: Use Zambone to manage your private documents on a server.

    • Weak: When setting up a file server, it is important to plan the directory structure carefully.

    • Strong: Plan the directory structure of the file server carefully before you set it up.

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

  8. 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.

Content tips

These tips are about things to do — and avoid — in what you tell users to do. Remember that thousands of readers trust Fedora Magazine to tell them how to carry out tasks. Be responsible and helpful, advocate best practices, and respect the user’s security and choice.

  1. 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.

  2. 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.

  3. 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.

  4. 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).

  5. 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.

  6. 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.

WordPress tips

  1. 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.

  2. 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.

  3. 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:

    • Enter a meaningful keyword in the SEO box under your article. (Most articles shouldn’t use Fedora.)

    • If the Snippet doesn’t give an effective introduction or summary in the sample search result, rewrite it.

    • Don’t feel like you have to eliminate every warning. A “green” rating overall is the only goal.

Other hints

Got an idea for better writing? Discuss with the editors on IRC Freenode at the #fedora-magazine channel.