Skip to main content

Top 10 tips for Dynatrace content creators

These top 10 tips for creating content at Dynatrace crystallize the best ways to be a user advocate while embodying the Dynatrace voice and style in your writing.

Write in the active voice (mostly)​

Active voice makes clear who's performing an action and empowers the user. In instructional content, for example, say "you can set up alerts" rather than "alerts can be set up." Active voice sounds confident, authoritative, and transparent, while passive voice can sound complicated and defensive. Active sentences are more conversational and easy to read.

However, passive voice is appropriate in some instances. Use passive voice when the action itself is more important than the actor performing the action, for example, when describing system behavior or in warnings.

Use American English spelling​

Although they’re broadly similar, American English differs from British English in several ways. We use American English spellings to ensure consistency across all content and communication. Refer to the Dynatrace word list for some commonly misspelled terms. For anything else, refer to the American Heritage Dictionary.

Provide useful and relevant information​

Provide information that anticipates and answers the needs of our users and customers. Make sure your information is accurate and precise as well as adequate—test your writing against product functionality. Is the information what the user is looking for? Is it in the right place? Check that the information is the best and most relevant solution to the problem at hand.

Write for scannability​

Users tend to scan pages and blocks of content rather than read text word for word. Scannable text reduces cognitive load by helping users find information quickly and retain it more easily.

  • Think structure, hierarchy, and flow when designing content—this goes a long way in helping users understand your content while scanning.
  • Use elements like headings, lists, expands, callouts, images, and tables to provide visual clarity and focus.
  • Provide introductions and summaries in your writing. Introductions tell the reader what to expect. Summaries briefly outline what follows.
  • Break up large blocks of text into crisp sentences and idea-specific paragraphs.

Lead with what's important​

Make it easy for the user to find value up front.

  • Front-load sentences with keywords and purpose so users know if they're in the right place.
  • Begin sentences with user concerns and purpose, for example, "To query Grail,...."
  • Provide key information within the first two paragraphs.
  • Focus your message and get to the point.
  • Highlight the main points of your writing and use headings, links, or expandable content elements to direct users to details.
  • Ensure key content doesn’t truncate and remains intact in UI labels, menu entries, table data, and elsewhere.
tip

Verify correct text display across all supported screen dimensions, including dynamic resizing and text wrap in web browsers.

Keep it conversational​

Follow our voice and tone guidelines to sound approachable as well as knowledgeable. Use everyday language and the most appropriate words for the situation, sticking to short and simple words where possible. Use common contractions like "we're" or "that's." Use simple tenses (past, present, future). Address readers in the second person. Skip the jargon—insider terms, cliches, and idioms aren't universally understood and make localization difficult. Check if your writing sounds conversational by reading it aloud.

Be concise​

Keep your sentences and paragraphs short and to the point. Be economical but not terse; write with mobile-device reading in mind. Cut the fluff—avoid unnecessary modifiers and vague statements.

Be consistent​

Use simple and standardized terminology consistently. Follow our word list and the Dynatrace Platform terminology. Correctly spell and capitalize third-party brand and vendor names.

Use parallel sentence structures where possible in lists and headings so they're easy to understand.

Follow punctuation guidelines​

Here are some high-level tips on using punctuation correctly and effectively.

  • Use a serial comma, that is, a comma before "and" in any list of three or more items. Commas play a key role in helping readers understand the correct meaning of sentences.
  • Don’t use ampersands (&) as an arbitrary replacement for the word "and." While there are exceptions for feature, capability, or app names, it's safest to avoid ampersands unless referring to an established name.
  • Use closing punctuation at the end of complete sentences, not phrases. Use a single space between sentences.
  • Don't use closing punctuation in headings.

Use sentence-case capitalization​

For titles, headings, and subheadings, sentence case is less formal and easier to read than title case. Capitalize only the first word and the first word after a colon in a subtitle. Be sure to correctly capitalize proper nouns such as named features and product names; all other words should be lowercase.