Guidelines for Writers

Important

All documentation must adhere to the F5 content style guide. The information provided here supplements the official F5 style guide.

Quick Ref:

  • Use a single space after a period.
  • Use Oxford commas.
  • Spell out numbers below 10 (“one”, “two”, “four”, etc.).
  • Use integers for numbers 10 and above.
  • Trademarks aren’t required in HTML content.
  • In print content (i.e., PDFs), trademarks aren’t required in titles and headers; you must use trademarks the first time you mention a product (e.g., F5® BIG-IP® Local Traffic Manager™).

Brand Considerations

F5 documentation must adhere to the F5 brand guidelines.

Content Types

For solution docs, we provide two general types of content: expository and instructional. We purposefully separate exposition from instructions to make it easier for users to find the specific tasks they need to complete to accomplish their goal. Provide links to the expository information from the instructional content (and vice versa). Users interested in the architecture or background can consult the expository docs and everyone else can simply move forward with the tasks.

Style and Voice

What did you actually read?

Were your eyes drawn to the list? Did they glaze over when you saw a block of text? Did you skip the paragraphs and come straight to this sidebar?

Keep this behavior in mind when writing your documentation. Our goal is to help users figure out what they need quickly, so they can get on with their lives.

Cloud documentation follows the F5 Modern Voice strategy developed by the Technical Communications team. The core principles of modern voice are:

  • Focus on the customer question.
  • Give a concise answer.
  • Make it easy to scan.
  • Use normal, relaxed words.
  • Empathize.

In other words, don’t go off on tangents. Don’t use 10 words when two will do. Pictures, lists, and tables are your friends. Use the same words in your writing that you’d use with a professional colleague. Don’t talk down to the readers. Trust that your readers have the required background knowledge to understand the concept you’re documenting. If they don’t, they’ll most likely find the information they need the same way they found our documentation – Google.

F5 Modern Voice Guidelines

Important

The content presented below is from the F5 Modern Voice guidelines. We recommend referring to that document directly for updates and additional information.

  1. The Cardinal Rule of Global English: “Don’t make any change that will sound unnatural to native speakers of English.”

  2. Corollary: “There is almost always a natural-sounding alternative if you are creative enough to find it.”

    The basis for Modern Voice are industry standards such as Minimalism, Simplified Technical English, Topic-Based Authoring, and Global English. It’s also based on analysis of customer research and trends. As always, customer satisfaction trumps everything, so there certainly are exceptions to these.

  3. General guidelines:

    • Restrict the length of noun clusters to no more than 3 words.
    • Restrict sentence length to no more than 20 words (task-oriented sentences) or 25 words (conceptual sentences).
    • Restrict paragraphs to no more than 6 sentences (in descriptive text).
    • Avoid slang and jargon, while allowing for specific terminology.
    • Make instructions as specific as possible.
    • Use articles such as “a/an” and “the” wherever possible.
    • Use simple verb tenses (past, present, and future).
    • Use active voice. Limit passive voice.
    • Do not use present participles or gerunds unless they’re part of a Technical Name.
    • Do not use gerunds in titles. Make titles active and direct.
    • Do not use metaphors or allusions that people in other cultures might not understand.
    • Use “‘s” to show possession with nouns that denote inanimate objects. Example: “…the field’s data area…”

  4. Avoid the ‘forbidden’ words

    These words aren’t actually forbidden, per se; but since nobody talks like this, we don’t write like this either.

    Forbidden Word Replacements
    Bad Good
    purchase buy
    modify change
    perform do
    terminate end
    obtain get
    utilize use
    navigate go
    terminate end
    image picture
    configure set up
    execute run
    resolve fix
    halt stop
    value number