Direct and indirect speech Edit

Highlight: In general, use indirect speech.

In documentation, sometimes you have to convey what someone has expressed from a previous conversation, to the reader. This can be done in two methods, direct speech or indirect speech. In general, use indirect speech so that readers don’t have to distinguish between speakers and their quotes.

Direct speech

In direct speech, the speaker’s words are directly quoted word-to-word without any change. The words that are spoken by the speaker are enclosed in quotation marks with a comma before the initial quotation marks to introduce the speaker. Use double quotation marks as per American (US) English guidelines. Punctuation such as a period, comma, question mark, exclamation mark should be inside quotation marks.

Examples

Developer’s expression: This API is the newest version.
Direct speech: The developer said, “This API is the newest version.”
Direct speech: “This API,” the developer said, “is the newest version.”

Avoid using direct speech by breaking up information about who is speaking. This impedes the understanding of the reader.

Top ↑

Indirect or reported speech

In indirect or reported speech, the speaker’s words are reported by paraphrasing or summarizing. Unlike direct speech, the words not quoted directly and there is no additional punctuation to be used. Verbs that better describe the person’s action are used while paraphrasing in indirect speech, whereas while summarizing, standard verbs like say, tell, talk, speak are used.

Examples

Developer’s expression: This API is the newest version.
Indirect speech (summarized): The developer said that this API is the newest version.
Indirect speech (paraphrased): The developer asserted that this API is the newest version.

Last updated: