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 unnecessary future tense. Unless you’re actually talking about future plans or publications, present tense is best.

    • Unnecessary future tense: When you select Run, your program will start.

    • Present tense: When you select Run, your program starts.

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

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

  9. 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. Avoid exclusionary or problematic language. These are examples of terminology to avoid wherever possible in articles:

    1. blacklist/whitelist — Use allowlist/denylist instead, which is more directly descriptive of the purpose.

    2. master/slave — Use primary/secondary, primary/replica, active/passive, active/standby, or another similar construct.

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

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

    1. Copr instead of COPR

    2. NVIDIA instead of Nvidia or nVidia

    3. Perl instead of PERL

    4. Red Hat instead of Redhat or RedHat

    5. ThinkPad instead of Thinkpad

Image and screenshot tips

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

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

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

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

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

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.

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

Other hints

Got an idea for better writing? Discuss with the editors in the #magazine:fedoraproject.org Matrix channel on chat.fedoraproject.org.