Technical Writing

What is technical writing? >Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. It encompasses the largest sub-field within technical communication. > >The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature". In this thread I am mostly concerned with points (1) and (3) above, as (2) would make posting to lainchan count as "technical communication". What sort of technical writing is there? There's a lot! You've almost certainly come across textbooks and documentation (electronic or in print), and may also have read academic papers. I would also categorise many blog posts as "technical writing" too. What is this thread? Writing to convey information is very different to writing to tell a story. The methods for one don't really transfer to the other. Let's have a thread about how to improve our technical writing. This thread is NOT just for sharing examples of technical writing. If you're going to share something, write a little about why it's particularly worth reading. I'll start with a few points that have been hammered into me by my adviser over the course of my Ph.D: >Do not use the passive voice. >Avoid emotive phrases and value judgements. >Beware of commas. Only say one thing in each sentence. >Do not use quotation marks unless you are actually quoting someone, and then include a citation. >Avoid parentheses. >Do not include key information as a footnote. Someone should be able to read your document without the footnotes and still understand it. >Avoid "this" and "it" unless the context makes it very clear what you are referring to. I recently read "A Guide for New Referees in Theoretical Computer Science" (https://www.cs.utexas.edu/users/dahlin/professional/parbery-referee.pdf), the "Quality Control" and "Technical Writing" sections may be of interest.

I am a great fan of using static analysis to help with my programming, and have recently started doing the same with my writing. proselint (http://proselint.com/) and vale (https://valelint.github.io/docs/) are linters for prose. Unlike spelling and grammar checkers, they instead concentrate on logic and word use. vale is much more opinionated than proselint, and the default configuration has far too many false positives for my liking, but with a little configuration I am liking the suggestions that both are giving me. As I am mostly writing LaTeX, I turn off the lints about fancy quotes and the like for proselint: { "checks": { "typography.symbols": false } } And I find I disagree too much with the ComplexWords, Hedging, and PassiveVoice checkers in vale: [*] vale.Annotations = suggestion vale.ComplexWords = NO vale.Editorializing = warning vale.GenderBias = suggestion vale.Hedging = NO vale.Litotes = suggestion vale.PassiveVoice = NO vale.Redundancy = error vale.Repetition = error vale.Uncomparables = error vale.Wordiness = warning I've integrated both tools with the emacs flycheck package, and have them run automatically on LaTeX buffers (along with the default LaTeX checkers), and the experience is pretty nice. I've directly implemented most of the suggestions, and the remaining ones are all either clear false positives (like identifying a repeated word in a fragment of code), or awkwardly-worded sentences I wasn't happy with in the first place.

How can I actually get better at it? I find writing very hard and somewhat painful, and rarely end up with text that I actually think is good.

I also got taught to avoid passive voice at all costs, I disagree. "The user is asked for input" vs. "The computer/system/software asks the user for input" "Access denied" vs. "The computer/system/software denies access" It's much clearer to use passive voice when describing things a computer is doing instead of starting each other line with "The software [verb]" or "The system [verb]".

>>740 The easiest way to get better is for someone who is better than you to proofread your stuff. Failing that, reading well-written things I suppose. >>741 As with all things, only a Sith deals in absolutes. "A Guide for New Referees in Theoretical Computer Science" has a good example of what I consider to be the "bad" sort of passive voice use: >It will be proved that ... vs >We will prove that ... Both convey the same information, but the former just sounds weaker, like the author is less certain of their result. They prove it, do they not? Then why don't they say that? And if they don't prove it, who does?

>>677 kudos for mentioning proselint and vale. I didn't imagine there is such thing, will definitely check them out next time I have to write something

>>740 I'm in a similar boat, Lain. I like to write instructions for myself to do things but I don't ever think it is good enough that I can give them to someone else and expect them to be able to follow. I think my problem is I'm not able to write good transitions from one part to the next. Looking back at my old writing, every topic just kinda begins randomly in the middle of the old topic and the old topic never properly ends.

>>740 >>782 There are 2 easy questions to always ask yourself which will improve your writing immensely: 1 - The key point in any communication is to know what it is you want to say. So ask yourself just that, "what message do I want to get across?" The answer is most likely a lot simpler than what you wrote, so just stick to that! 2 - The second point, which can be more difficult, is to know why you are writing this email/report/etc... so ask yourself "what is the outcome I want from this communication?" You don't write anything without a purpose; make sure that the message of your piece is clear and also serves your needs! Prepare your draft, and make sure that every sentence and piece of information included serves either purpose. Extra tip: In top reports, articles, statements of purpose, etc... one paragraph only has one message and serves just one purpose within the whole. The first sentence clearly summarizes what the paragraph is about. This helps grab the attention of readers who would otherwise only skim through your work. I'm pretty sure that tip got me into Harvard and Princeton! I hope this helps. Good luck, and don't give up!

My personal recommendations for improving the quality of one's technical writing are provided below: I have a personal physical copy of Australian guide to corporate communication : a practical handbook on effective writing & speaking (http://www.worldcat.org/title/australian-guide-to-corporate-communication-a-practical-handbook-on-effective-writing-speaking/oclc/62540790), that I was required to purchase as part of my undergraduate studies and has served me well as a reference for corporate communication in general including technical documentation and writing. I used it mainly for its information about various genres and for its information and suggestions regarding target audience and suitable level of discourse. As I can't find an ebook of this please find several other ebooks as attachments , though I haven't used them personally as references yet, I have just had them recommended to me by other people. Other recommendations I have on material for technical writing, include the conference presentations of Lana Bridley (http://lanabrindley.com/videos/), one of which I had the pleasure of being the camera person for. The alternate sources for the videos (non youtube where possible) are given below: For Open Source Documentation for the Terminally Illiterate https://www.youtube.com/watch?v=25ubhjD1XV4 http://mirror.linux.org.au/pub/linux.conf.au/2011/2011-01-26-Wednesday/L101/Open_source_documentation_for_the_terminally_illiterate.ogv How Good Are You Really? Improving Your Technical Writing Skills http://mirror.linux.org.au/pub/linux.conf.au/2012/How_good_are_you_really_Improving_your_technical_writing_skills.ogv There and Back Again: An Unexpected Journey in Agile Documentation http://mirror.linux.org.au/pub/linux.conf.au/2014/Thursday/98-There_and_Back_Again_An_Unexpected_Journey_in_Agile_Documentation_-_Lana_Brindley.mp4 8 writers in under 8 months: from zero to a docs team in no time flat http://mirror.linux.org.au/pub/linux.conf.au/2015/OGGB3/Thursday/8_writers_in_under_8_months_from_zero_to_a_docs_team_in_no_time_flat.webm Every Page is Page One: A demonstration involving bears, and Play Doh http://mirror.linux.org.au/pub/linux.conf.au/2015/Case_Room_2/Monday/Every_Page_is_Page_One_A_demonstration_involving_bears_and_Play_Doh.webm Content as a driver of change: then and now http://mirror.linux.org.au/pub/linux.conf.au/2017/Content_as_a_driver_of_change_then_and_now.webm I like Lana's talks because of her background, experience and approach to communicating about technical writing and documentation, it was fun to participate as an active audience member in the impromptu workshop on collaborative real time documentation. Additional resources I recommend for improving ones technical writing include: The works of Edward Tufte regarding data / information visualization (for attachments see the following post) , I first discovered this in my data visualization and analysis classes, but it is very important to display of textual information as well. Github awesome lists on book authoring, and examples of beatiful documentation. https://github.com/TalAter/awesome-book-authoring https://github.com/PharkMillups/beautiful-docs Documentation Guide from http://www.writethedocs.org/guide/# and The Hitchhiker's Guide to Documentation http://docs-guide.readthedocs.io/en/latest/ Also see the Data Journalism handbook. http://datajournalismhandbook.org/1.0/en/ The attached books are User Guides, Manuals, and Technical Writing: A Guide to Professional English [1 ed.] by Adrian Wallwork This book is intended for anyone whose job involves writing formal documentation. It is aimed at non-native speakers of English, but should also be of use for native speakers who have no training in technical writing. Technical writing is a skill that you can learn and this book outlines some simple ideas for writing clear documentation that will reflect well on your company, its image and its brand. The book has four parts: Structure and Content: Through examples, you will learn best practices in writing the various sections of a manual and what content to include. Clear Unambiguous English: You will learn how to write short clear sentences and paragraphs whose meaning will be immediately clear to the reader. Layout and Order Information: Here you will find guidelines on style issues, e.g., headings, bullets, punctuation and capitalization. Typical Grammar and Vocabulary Mistakes: This section is divided alphabetically and covers grammatical and vocabulary issues that are typical of user manuals. Technical writing : a practical guide for engineers and scientists by Phillip A Laplante Engineers and scientists of all types are often required to write reports, summaries, manuals, guides, and so forth. While these individuals certainly have had some sort of English or writing course, it is less likely that they have had any instruction in the special requirements of technical writing. Filling this void, Technical Writing: A Practical Guide for Engineers and Scientists enables readers to write, edit, and publish materials of a technical nature, including books, articles, reports, and electronic media. Written by a renowned engineer and widely published technical author, this guide complements the traditional writer’s reference manuals and other books on technical writing. It helps readers understand the practical considerations in writing technical content. Drawing on his own work, the author presents many first-hand examples of writing, editing, and publishing technical materials. These examples illustrate how a publication originated as well as various challenges and solutions. The Handbook of Technical Writing [11ed.] Gerald J. Alred, Charles T. Brusaw, Walter E. Oliu From formal reports and manuals to everyday e-mails, The Handbook of Technical Writing uses smart, accessible language to spotlight and clarify technical writing today. Hundreds of topic entries, 90+ sample documents, at-a-glance checklists, and dynamic videos break down the best-practices, models, and real-world skills that successful writers use to clearly and persuasively communicate technical information and data. Developed by a legendary author team with decades of combined academic and professional experience, the book’s intuitive, alphabetical organization makes it easy to navigate its extensive coverage of grammar, usage, and style. Plus, updated, in-depth treatment of pressing issues like the job search, the writing process, documenting sources, and social media resonates both in class and on the job. With a refreshed, integrated focus on the ways technologies shape writing, the Eleventh Edition of the Handbook is the indispensable reference tool for writing to workplace success.

The first attachement is The Elements Of International English Style: A Guide To Writing Correspondence, Reports, Technical Documents, And Internet Pages For A Global Audience by Edmond H. Weiss. (alternative link https://saidnazulfiqar.files.wordpress.com/2008/04/element-of-english-style.pdf) The Elements of International English by Edmond H. Weiss is written to satisfy a wide range of audiences from different fields. The audiences are most likely business students, graduate and undergraduate students, technical writers or editors, or perhaps people doing some linguistic research. The author gives the audience a very brief and simple explanation about the use of English to document projects and write reports, letters, and memos from an international perspective. The audiences targeted in this book are mainly nonnative speakers of English who can relate these writing rules to their goals and career. Keeping these audiences in mind, Weiss divides the book into seven simple chapters. In the first chapter, “The Language of Global Business is International English,” the author gives a quick overview on native and nonnative speakers of English, usually referred to as E1 and E2, respectively. However, this shorthand notation is confusing as readers may tend to forget what it refers to no matter how many times they come across the particular acronym. One survey in the book surprised me; it revealed that approximately 1.5 billion people in the world speak English, and most are nonnative speakers. Especially effective is the statistical study of Mandarin Chinese and English, which explains that the proportion of E1 people learning English is less than that of the E2 people (Chinese learning English). The author gives a very good introduction by discussing the importance of English in terms of globalization. Weiss talks about the International English style that helps readers acquire a set of rules throughout the world for business and commercial applications. The author urges writers to eliminate scientific phrases and to use proper and simple verb forms and short, plain words. Also, for him, content alone is not the only concern; page layout is also important. I liked the examples where Weiss replaces the word needs with simple, short, and familiar words like demand and request, based on the situation. The simple acronym CBS (clear, brief, sincere) helps readers remember to apply these principles while writing. In the second chapter, “Principles of Simplicity,” the author discusses various rules to be followed while writing. This chapter would be improved by a clearer explanation of its relationship with the first chapter. However, the author does a good job of presenting principles, such as asking writers to choose words having one or a few meanings and to use proper word choice, tense forms, and vocabulary. Weiss suggests that proper usage of items like references and footnotes, as well as usage of technical words, makes writing easier for readers to understand. He talks about the various reasons that English is difficult, discussing issues like its immense vocabulary, risk factors due to interpretation of wrong meanings by E1 and E2 readers, and Odgen's Basic English. Odgen's basic language includes a set of prefixes and suffixes, rules of permitted verb forms, and other techniques that would speed the learning of English and make it harder to misunderstand [p. 17]. The author also discusses the language achieved through recent developments, such as avoiding nominalization (changing direct verbs to pseudotechnical expressions like reach a decision for decide), commercial tools to aid writing, and software for creating simplified and controlled versions of English. In the third chapter, “Principles of Clarity,” the author deals with various ways of writing that will reduce confusion for E2 readers, especially with the usage of who and whom. The author warns writers to avoid using only, nearly, and almost in the wrong place and not to confuse frequently used terms, such as like and as, effect and affect, and lie and lay. In addition to the many examples that Weiss gives, he could also have included some of the simple differences, such as between its and it's. He emphasizes using clear standard spellings based on which English the readers are using and being aware of the several English styles related to spellings, money, and dates. He encourages writers to avoid illogical sequences of words, words having opposite meanings, abbreviations, contractions and acronyms, literary and cultural allusions, military and sports vocabulary, unnecessary technical terms, and sarcasm or irony. In Chapter 4, “Reducing Burdens,” the author suggests ways to improve readability. Readability is enhanced when writers use perfect page layout, shorter sentences in place of compound or complex sentences, and punctuation, and when writers convert paragraphs to lists, tables, and play scripts. However, readability decreases when a writer starts using dashes, commas, hyphens, quotation marks, and so on. Weiss discuss how proper page layout and design decrease the burdens faced by readers and increase the speed, readability, and comprehension of content. Weiss's fifth chapter, “Writing for Translation,” talks about the need for writing translations that are mostly bilingual. The author feels that most translations are done by E2 writers, and they normally fail because it is difficult for them to translate content when the sound and rhythm contributes to the meaning or when there are some echoes and connotations associated with the words. The author examines the differences in rendering a text in two languages, and he feels that most E2 readers prefer reading the original version rather than the translated version. Automatic translation software helps in translating English to a second foreign language. However, most of the translations are based on false assumptions about the meaning of a particular word, leading to a major failure. Chapter 6, “Principles of Correspondence,” talks about rules for writing letters and emails in North American business. The author divides the chapter into two sections, letters and emails. Business letters and emails, as a rule, rely more on vocabulary and not on structure. Weiss talks about the two formats while writing in two different perspectives: the receiver's style, which is prone to more errors, and the sender's style, which seems to be the safer one. The author does a very good job of informing E2 readers about how to compose bad-news letters. I feel this is the most difficult act for an E2 reader: to share his or her feelings or thoughts in writing. The author talks about the globalization of email, although he does not discuss security issues when sending files or important messages as attachments. The last chapter, “Principles of Cultural Adaptation,” discusses the issues and controversies associated with intercultural communication and business transactions. Weiss debates these aspects in terms of philosophy and rhetoric. The author gives a basic idea to his readers about certain behaviors they will have to exhibit in various cultural environments. Examples like following proper rules while driving in different countries with unfamiliar steering-wheel locations or traffic and warnings signs make for an interesting discussion of intercultural differences. The author believes in formal communication, which means following prescriptive grammar and avoiding sentence fragments. The author talks about the concept of “radical localization,” a concept put forth by Nancy Hoft, which involves not simply editing a document for ease, simplicity, and clarity but also adding elements that appeal to the interests of local readers. The author also talks about graphics usage in lieu of paragraphs and text to reduce the burden of reading, but only when there is a standard form used all over the world, like in mathematics. Finally, Weiss recommends writing for a range of audiences, thus solving the problems of intercultural communication. In general, Weiss imparts a range of knowledge about writing for both E1 and E2 readers. The page layout of the book contributes to its readability, with visual cues clearly differentiating between paragraphs, headings, tactics, and examples. Labels of Before and After on examples allow the readers to have a feel of how a text has been changed from the previous version to the present one. Examples are presented consistently throughout the book and hence are easy to understand. Likewise, the tactics in every chapter are all written in a simple manner when you read them out of context. One weakness of the book is that the author repeats points about proper word choice, vocabulary, and tense forms in almost every chapter. It may be rather confusing or irritating to readers to read the same content multiple times. Also, as mentioned, a clearer connection is needed between the first and the second chapters; this could be achieved by forecasting the second chapter at the end of the first chapter. A final area for improvement is that the book would benefit from better comparisons of British and American English. Overall, however, Weiss does a good job of conveying simple rules and information, along with interesting examples, for E2 readers. I would surely recommend this book to any audience who wants to learn about the principles of simplicity, clarity, and usable layout in writing. Nonnative speakers of English will find this book especially useful. The second attachment is a Communication Skills Guide published by the University of Adelaide. The third attachment is a presentation given at MIT on Technical Writing.

The Edward Tufte attachments as mentioned above, for elaboration on them see https://www.edwardtufte.com/tufte/books_vdqi

The Edward Tufte attachments as mentioned above continued.

>>963 >>964 I've read the first one, but I'm so happy to have these others now. Thank you.

>>961 >>962 >>963 >>964 Thank you for the great posts and books!

would you say you need to be able to program to do this? is it necessary at all

>>1669 To do technical writing? Not at all. Technical writing is in (in my view) a core life skill like cooking or arithmetic; everyone should be able to do it to some degree.

I'm a computer science major how do I get my foot in the technical writing door? I've always been praised for my writing and professors have commented my writing is probably the best out of all the CS students

Can i learn english?

>>1687 If your professors are praising your writing, then you're already doing technical writing. Are you asking how to get paid to do technical writing? If so, there are internships in software companies for people who can write good documentation and help files for users. If you're wondering how to get (even) better at technical writing, I suggest documenting your assignments and personal projects. You could also try literate programming. I like to use org-mode for writing lab reports. It has some very powerful literate programming features. I highly recommend checking it out when you have a bit of time to learn your way around a new tool.

>>1692 Thanks for the help. I'll try to look into org-mode when I can. Find some tutorial . I'll also try to look for internships, but most of the ones I find and see advertising for are programming internships and not writing.

What IS technical writing? Can you write technically? Of course not. But you can technically write.

How do I do this for a living? how do i get ajob? someone help

>>1696 >What IS technical writing? Writing for technical purposes, rather than academic purposes (essays on philosophy or politics or analysis of literature) or artistic purposes (novels, poems). A non-exhaustive list of examples of technical writing: * Sending a memo to your employees notifying them of a policy change or a meeting. * The manual for a product you sell. * A grant proposal to a government agency asking them to fund your scientific research. * Documentation for employees with the correct procedures on how to log into the company VPN and access their email. * A formal proposal detailing the plan for a project, along side timelines and budgets. * A report presenting and summarizing the results of an experiment or research project. * The map in an apartment building showing the way to the closest fire escape. * Advertisements as a whole.

>>1692 WhAT IS ORG MODE HOW DO YOU INTO IT? WHAT IS A TEXT EDITOR