I graduated with a BA in English with a Technical Writing concentration 15 years ago. I did the job for a few years and, honestly, it sucked. At best, I was treated like an idiot by developers. Developer aloofness seemed much worse back then — they were never wrong. I was always at the end of the software development cycle, so there was never enough time budgeted to do good work. Management couldn’t decide if I was a tester and a writer, so I often had to fill both roles. The rapid nature of software development today is great for users and developers, but lends itself to rapidly expiring documentation. I did the job long enough to teach myself software development. I switched over to being a software dev ten years ago and have never regretted it. Entry level pay as a software dev was better than experienced pay as a technical writer. I have been asked to write documentation, and I’m glad to do it — just not as my primary duty.
After reading some of the comments here, I'm wondering if people are actually following the link and reviewing the content.<p>The two courses are well-structured. Each course has an overall outline listing each lesson, and each lesson has a table of contents to overview the topics therein. The courses highlight major key topics in technical writing and does so with easy-to-internalize (tenets). I'd have loved for my university coursework to be so clearly organized.<p>Some highlights include defining your audience[1], engaging your audience[2] and reviewing how short and clear sentences improve comprehension[3].<p>1: <a href="https://developers.google.com/tech-writing/one/audience#define_your_audience" rel="nofollow">https://developers.google.com/tech-writing/one/audience#defi...</a><p>2: <a href="https://developers.google.com/tech-writing/one/active-voice" rel="nofollow">https://developers.google.com/tech-writing/one/active-voice</a><p>3: <a href="https://developers.google.com/tech-writing/one/short-sentences" rel="nofollow">https://developers.google.com/tech-writing/one/short-sentenc...</a>
This is why “nobody reads documentation.” These courses are typical tech-writer overkill, missing the forest for the trees, then getting lost in the weeds (if I may mix a few metaphors). There is too much introduction and setup, then it jumps into the nitty-gritty, but never gives the big picture.<p>Assuming this was written by the Google tech writers, I’m surprised at how middle-of-the-road the offering is. I kinda assumed they had an academic-like cutting-edge writing department.<p>To write documentation, you need 2 things: an understanding of the subject matter, and a high-level understanding of what the readers want to do. The reader doesn’t want to use your API to list resources, the reader wants to give his/her users a list of resources for further operations. So you don’t give a trivial example of getting the list of providers, you give an example of how to display providers by getting the list and processing the various useful fields.<p>It also helps if the API or UI or whatever is logical and consistent to begin with.
The best i have seen is the economist style guide - <a href="http://cdn.static-economist.com/sites/default/files/pdfs/style_guide_12.pdf" rel="nofollow">http://cdn.static-economist.com/sites/default/files/pdfs/sty...</a><p>the US Army writing style guide for leadership is also pretty good - <a href="https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/Writing_Style_Guide.pdf" rel="nofollow">https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/...</a><p>The examples here are very very good.
Good resource. One common flaw i see in many technical writings, which i missed from the course, is treating the reader as a complete puppet. As in giving copy-paste instructions on what to do, but not explaining what's happening underneath.<p>Better to teach a man how to fish than giving away a fish, or better condensed by Fred Brooks famous quote from Mythical Man Month: <i>Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.</i>
I find writing documentation very relaxing. After a particularly busy dev cycle, it almost feels like a nice break. Maybe I should take one of these courses; I think we have more ageism in development than in technical writing (just a hunch without any evidence/citation).
I'd love a technical PowerPoint course. I find writing to be pretty straightforward. But when manager is like "can you create a couple slides about...." total deer in the headlights.
Teaching of <i>writing</i> has long been mostly about teaching how to write <i>belle lettre</i>.<p>Some of the lessons there can also apply to technical writing, e.g., have in mind and track the reactions of the intended audience. E.g., the script writers for good movies, along with the director and actors, etc. do well having in mind, "tracking", and <i>bringing along</i> the audience, e.g., in what appears to be relatively technical content for movie audiences, the movies <i>Star Wars</i>. So, e.g., anticipate the audience reaction enough to see that they won't get lost and give up.<p>But let's set aside <i>belle lettre</i>, courses in "creative writing", etc. and move on:<p>It turns out there are some technical fields that have long had essentially their own <i>techniques</i> of writing. The writing in those fields is especially good on precision. The better writing examples from those fields can serve as good examples for maybe nearly all technical writing. IMHO, from my experience, some of the best examples include:<p>o The original Kemeny-Kurtz documentation on their programming language Basic.<p>o McCracken's documentation of Fortran.<p>o Any of the freshman college physics books by Sears, <i>et al.</i>.<p>o Any of the best freshman college calculus books.<p>o IMHO, D. Knuth's <i>The Art of Computer Programming</i>.<p>One way to make some progress on doing such writing is to take a college course in abstract algebra where the homework is to write proofs and where the teacher reads and corrects the <i>writing</i> style, technique of some of the homework. For a student who was taught writing <i>Belle Lettre</i> where often ambiguity is desired and precision is not, an abstract algebra course can be a good step forward for technical writing.
From "Zen and the Art of Motorcyle Maintenance" (<a href="https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-RobertPirsig/mode/2up" rel="nofollow">https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-R...</a>)<p>> "But they’re from the factory," John says.<p>> "I’m from the factory too," I say "and I know how instructions like this are put together. You go out on the assembly line with a tape recorder and the foreman sends you to talk to the guy he needs least, the biggest goof-off he’s got, and whatever he tells you. ..that’s the instructions. The next guy might have told you something completely different and probably better, but he’s too busy."<p>> They all look surprised. "I might have known," DeWeese says.
I’ve been writing my entire life.<p>I’ve found writing in the vernacular is usually the most effective approach (speaking only for myself -YMMV).<p>In my opinion, I think that there are a number of “base class” rules for tech writing, but each subject domain really requires a distinct approach, as well as a clear understanding of the audience (and subject matter -but in my experience, being a good writer/teacher is more important than being a subject matter expert. The worst teachers I ever had were subject matter masters).<p>But this is a cool resource.<p>The one critical thing I find for my writing, is that the information I give be 100% correct, and the accompanying materials be absolutely polished and tested out the wazoo.<p>If I’m speculating or unsure, I’m careful to note that.<p>Mild humor helps, but I need to be extremely careful, and it’s usually self-deprecating.
Page layout matters, and Google's has become cluttered. For example, <a href="https://cloud.google.com/sql/docs/postgres/private-ip" rel="nofollow">https://cloud.google.com/sql/docs/postgres/private-ip</a> It's so busy I've been opening the browser console to delete sections: the fixed header over 100 pixels tall, the left-column site map, the right-column page map, and the footer. This is what happens when you let Marketing design documentation.<p>I believe part of the problem is also the font. Roboto is okay for a user interface. For prose I prefer serif.<p>My favorite page layout: <a href="http://www.linfo.org/" rel="nofollow">http://www.linfo.org/</a>
I've been working on this tool for a while that makes documentation easier and faster. The main idea is to have the code itself be the driver. Would love some feedback: <a href="https://trymaniac.com" rel="nofollow">https://trymaniac.com</a>
What do you think, technical writing should be included in the daily job of engineers, or is it ok if the company is hiring people with some low technical skills/experience in favor of some target-language-Bachelor-of-Arts students to do these tasks?
The content seems good but I'm not a fan of the way the sections are laid out on the introduction page. The courses should at the very least have hyperlinks for each of the learning objectives.