Guidelines for Writers

Important

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

Brand Considerations

F5 documentation must adhere to the F5 brand guidelines.

Content Types

For User Guides, we provide three types of content:

  • Task
  • Tutorial
  • Concept

These content types generally follow the Kubernetes Documentation Style Guide.

Style and Voice

Docs like code projects follow the F5 Modern Voice strategy. 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
    retrieve get
    utilize use
    navigate go
    terminate end
    image picture
    configure set up
    execute run
    resolve fix
    halt stop
    value number