search

voedger / kb

Knowledge base
0 stars 0 forks source link

Writing style guidelines #49

Open maxim-ge opened 6 months ago

maxim-ge commented 6 months ago

Verb tense

Question:

I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names.

My ideas are:

  • Continuous (-ing) form: (e.g. "Creating a Cluster", "Creating a Database", ...)
  • Descriptive form: (e.g. "Cluster creation", "Database creation", ...)
  • Imperative form (e.g. "Create a Cluster", "Create a Database", ...)

Any other ideas?

Verb tense for technical document titles

Answer:

Imperative has my vote, by far. It is the clear winner in my professional opinion (IMPO) for the types of tech docs I write and most types I read and edit. I write mostly end-user how-to guides with step-by-step procedures and a few introductory and "about" guides or parts of guides.

Note, too, that I avoid -ING words if possible and follow global English guidelines. This is primarily because some languages have no equivalent to -ing words. Literally: -ing words don't translate to some languages. In today's global world, whether my docs are translated by my company or not, for years I've written with the assumption that many of my readers are reading English as a second language (ESL) and they either programmatically (browser or other tools) or in their minds translate my text into their own language.

Imprerative usage examples

Capitalization

Microsoft style uses sentence-style capitalization. That means everything is lowercase except the first word and proper nouns, which include the names of brands, products, and services. (Microsoft has more than 500 offerings. To help customers recognize, find, and buy them, reserve capitalization for product and service names.) ... Occasionally, title-style capitalization—capitalizing most words—is appropriate. For example, product and service names, the names of blogs, book and song titles, article titles in citations, white paper titles, and titles of people (Vice President or Director of Marketing) require title-style capitalization. In a tweet, it's OK to use title-style capitalization to highlight the name of a quoted article.

https://learn.microsoft.com/en-us/style-guide/capitalization

Examples:

maxim-ge commented 6 months ago

Examples

Mixed

Not capitalized

Capitalized