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.

WordPress tips

  1. Provide a featured image. Look at the information here for tips on featured images.
  2. 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.