Talk:Technical writing/Style

Second person

Second person is basic to modern professional technical writing--whoever keeps championing third person is wrong. Third person has an occasional role, but most projects require that you write as if speaking directly to the reader: not "The mechanic uses a socket wrench to remove the part," (3rd person) but, "Use a socket wrench to remove the part" (2nd person).

This statement is incorrect. When writing instructions the reader should never be directly addressed. Second person is fine as long as the reader is not directly addressed. Doing so looks unprofessional. For example: "Use a socket wrench to remove the part" is fine, but "You will use the socket wrench to remove your part" is unprofessional. (The preceding unsigned comment was added by 140.182.96.209 (talk • contribs) 15 April 2020)

Third person

Third person is less effective in technical writing than second person.

<This is incorrect> (The preceding unsigned comment was added by 140.182.96.209 (talk • contribs) 15 April 2020)

Examples: The user clicks the Add button. (3rd person) Click the Add button. (2nd person)

WRONG:

You will click the add button (2nd person, directly addressing the reader) (The preceding unsigned comment was added by 140.182.96.209 (talk • contribs) 15 April 2020)

As a rule, stay away from future tense and passive voice.

The use of negatives

Casual documentation and marketing may allow or approve the use of contractions. Technical Writing, which is a form of scientific writing, does not. The words doesn't, wouldn't, couldn't, don't, an't, etc., are unacceptable.

Second person, contractions

The technical communications program at the University of California Berkeley, for one, advocates second person and teaches that contractions are usually fine. I've never talked to a fellow STC member who had a problem with either. "Wouldn't" and "couldn't" don't come up much because technical writing strives for present tense, but "don't" is fine in most document types.

Technical writing isn't a kind of scientific writing—scientific writing is a kind of technical writing. That's not a trivial distinction. There are many types of technical writing, of which scientific writing is only one.

The Microsoft Manual of Style is a poor authority to cite. It's a corporate style guide that—if you must read a lot of MS docs, as I do—even Microsoft writers don't always follow. The Chicago Manual of Style is far better researched and organized.

Comment

Chicago Manual of Style is what the Microsoft style is based on. IBM style is also similar to Microsoft style. We commonly write technical documents in third person. Scripts (training) for speakers may be written in second person.

-

• The class technical communications course you speak of at Berkely suggests several reference manuals for successful college writing. My suggestion is that you read and use the exercise booklet.
• I am not sure what you learned in college, but your education is shy of the views of most educators. (casual, informal, speak)
• Sometimes we do use second person to address the audience directly. However, if we did this on a daily basis, throughout our documents, we would not be considered as having a good command of English.
• Though the media may utilize sentence structure such as: He states, "My sister and me...;" a learned writer, writes: He states, "My sister and I..."
• Writing sentences with contractions such as: I'll does not make for a powerful speaker, either. Frankly, I would not vote for a politician who presented his speech in this manner [1][2].

There are many cases where Technical Writers are required to document application functionality of programs that perform scientific functions. Additionally, many Technical Writers perform daily work tasks in a technical environment. For example, technical support, development, and engineering.

Example (Microsoft Style)

• The WpdHelloWorld sample driver supports four objects: a device object, a storage object, a folder object, and a file object. Each object supports corresponding properties. These properties are defined in the file WpdObjectProperties.h.

• The Port and PortSet queueing primitives, see CCR Ports and PortSets. The Port class is a first in first out (FIFO) queue of items - an item can be any valid Common Language Runtime (CLR) type (only items of that type, either CLR base types or user-defined types, can be posted to the port). In most cases there is also a queue of receivers (user code "guarded" by an Arbiter, which means that the Arbiter controls the execution of tasks by filtering the incoming messages as appropriate).
• The return value indicates this is a C# iterator over CCR ITask instances and informs the compiler that the method body might contain yield statements.

               yield return portInt.Receive();  

• Traditional failure handling schemes follow these patterns:
  • For synchronous invocations of methods, the caller checks one or more return values from the method. The method uses the callers execution context, most often this is a thread, to run.
  • Using structured exception handling, the caller wraps synchronous method invocations in try/catch/finally statements and either relies exclusively on the catch{} block for error handling. It may also use a combination of the catch{} block plus explicit checks on the results from the method.
  • Transactions which rely on a variety of compensation implementations by the components being called, OS infrastructure and usually expensive mechanisms to flow context across threads.

The Science of Computing

User based documentation may not be very scientific, but writing for an engineering (mechanical, development, etc.) community requires some level of knowledge beyond basic English. Writing a course on Technical Writing should include commonalities based on a technical environment.

• Technical writing is related to a science. The science of the computer, language and its functions.
• Technical writers, write in many mediums and the audience, technical aspects, and style vary.
• Technical writers are expected to have a good grasp of English. Editors / reviewers only handle minor punctuation and grammer issues.
• Terminology is as important to technical writers as is the scientific study of the application design.

Third Person Usage

"UC Berkeley's (Berkeley has) eight museums and its many collections support research and teaching in disciplines including anthropology, architecture, art history, art practice, botany, engineering, entomology, film history, geology, history, linguistics, paleontology, physics, and zoology."

• Sarah Yang and Robert Sanders, Media Relations | Berkely Using Contractions in Third Person

Example 1) A new paper reviewing the impact of the loss of large predators and herbivores high in the food chain confirms that their decline has had cascading effects in marine, terrestrial and freshwater ecosystems throughout the world. The study, co-authored by UC Berkeley researchers, highlights the impact “apex consumers” have on the dynamics of fire, disease, vegetation growth, and soil and water quality.

Example 2) On Sunday, July 17, the moon will acquire its second new companion in less than a month. That’s (that is) when the second of two probes built by the University of California, Berkeley, and part of NASA’s (NASA has - possessive) five-satellite THEMIS mission will drop into a permanent lunar orbit after a meandering, two-year journey from its original orbit around Earth.

• Robert Sanders, Media Relations | An example of the technical in writing

Example 3) The new NRC report, "A Data-Based Assessment of Research-Doctorate Programs in the United States," synthesized data about more than 5,000 programs in 62 fields at 212 universities with research-based programs. Originally anticipated in 2007, the rankings are based largely on data from the 2005-06 academic year and analyze doctoral programs in the physical sciences and mathematics, agricultural and life sciences, health sciences, engineering, social sciences, and arts and humanities. The voluminous report is online.

Example 4) The R (or regression-based) rankings are based on an indirect way of determining the importance faculty attach to various characteristics. First, groups of randomly selected faculty were asked to rate the quality of a sample of representative programs in their field. Based on the sample program ratings, weights were assigned to each of the 20 characteristics using statistical techniques; again, these weights varied by field. These weights were applied to the data about each program, resulting in a second range of rankings. Each approach yielded a different.

• Preface Page of Chicago Manual of Style| Third Person [3]

Example 5) This, the sixteenth edition of The Chicago Manual of Style, marks the first edition to be prepared and published simultaneously in print and online. As opportunities for publishing have grown dramatically in an era of electronic publication and distribution, the guiding principles for this edition have been twofold: to recognize the continuing evolution in the way authors, editors, and publishers do their work, on the one hand, and to maintain a focus on those aspects of the process that are independent of the medium of publication, on the other.

• Casual or creative writing (informal) may allow some (positive) contractions.
• The contractions: wouldn't, can't, musn't, won't, don't, etc., are unacceptable in technical documentation (formal).

Additional Information on Third Person

• http://www.mrsec.wisc.edu/Edetc/research/slides/Active-passive_handoutA.pdf
• http://www.ee.uconn.edu/SeniorDesign/designone/Lecture%2007%20Technical%20Writing.ppt

Wrong

I've know some decent technical writers who successfully learned on the job, but many writers wander into the field from engineering, journalism, or other writing or technical disciplines without learning (preferably from a reputable certificate or graduate program) the "technical writing style." You can spot them by things like their fondness for passive voice, third person, and words like usage and utilize.

To be clear, third person has a place, and the Technical Writing Style article should reflect that. Sometimes a document, or an aspect of a document, describes what others did and what those actions made happen. This is common, of course, in science writing, but much less common in the many other forms of technical writing. Marketing text, like the Berkeley museum text you cite, frequently uses third person, but that's not technical writing.

Most technical writing tends to be procedural, and--keeping with the tech comm axiom of "talk to the user," should be in second person. It delivers information to someone who must take action based on that information. You wouldn't give driving directions to someone by saying, "The car goes down this road and turns left at a gas station." You'd say, "Go down this road and turn left at the gas station."

Second person can be overdone if the writer chants "you" multiple times a paragraph--which I've seen in tech writing competition entries.

Comment

If the goal for the technical writing class is to teach an informal technical writing method, then specify it. Otherwise, the global audience you seek will not honor your work. I have never been in a business environment where informal writing, in second person, is acceptable other than in blogs, marketing / advertising, comments, and email(sparingly). Please enlighten us on your experience!

• The many writers you speak of are more educated (experienced) than the technical writer who just received a certification in technical writing. Their backgrounds are specific to that of engineering, medical science, journalism, etc., this means they are highly technical. Insisting that second person is the appropriate grammatical choice for every technical environment or preferred, is still incorrect. In many cases, terminology also dictates a grammatical person.

• Writing active voice, third person is much more complex than writing in second person for any writer. Additionally, whether you are writing technical documentation or a research paper, writing consistently in active voice it is not always possible.

• Second person is commonly written using an informal method. We both agree that second person is overdone. This grammactical person has been seen throughout the Wikiversity.

• I would never write, "You'd say," in a technical document. This is a lazy and bad writing habit. I am not sure why you feel that this is a form of clear and concise writing. The contraction itself has two meanings.

• Here is a question for you, "As technical writers, why do we define acronyms in our documents?" Answer: Acronyms have more than one meaning.

Recents Edits

• The statement that "technical writing leans towards second person," is incorrect.
• Some of the edits were reordered under Application Consistensy for clarity.
• Some of the content was removed under the topic, Understand your environment.
• Understand your environment has nothing to do with the use of the pronoun "you."
• Some of the recently added paragraphs on Chicago Manual of Style under the topic Specifying Gender have been removed. Primarily because the information is unrelated to the topic. We believe an anonymous editor has done this to prove a point rather than create value in the page.
• We do not write business communication in second person, informal. Emails, comments, requirements documents, technical specifications, etc., are written in third person.
• Second person (conversational, informal) is a common writing style in marketing communication. Though studies may indicate that technical documentation written for a global audience benefits from this technique (shown through the publication and popularity of the Dummies books), the use is not accepted inside the business environment.

Break down?

This page is too long, I am going to break it down into a more manageable form. AlistairReece 06:33, 17 August 2007 (UTC)

Most of this is inaccurate. I'd like to see the credentials of the original author. (The preceding unsigned comment was added by 140.182.96.209 (talk • contribs) 15 April 2020)