Technical Writing Courses
developers.google.com
developers.google.com
If you have agile, in theory all developers are replaceable. In reality, a few have writing skills, but most don't.
There’s no sense in work cultures I’ve experienceD that engineers should take in documenting their work individually, but having code do what it says on a deep level promotes, ah, grok-ability. But maybe leaving at that leads us inevitably to flawed self-documentation.
Seen it so many time in poor quality project. Hardly ever in project that have a high quality bar set.
I've done some technical writing. It's hard work. One open source tool I made, I spent more time on the docs than on the actual code.
Press releases, manuals, installation instructions, etc can be great QA/QC tools. If something is hard to communicate, then the subject itself is probably too complicated. Or just badly designed. Go back and simplify.
One stretch, I was also the engineering manager for a handful of products. So I had the juice to compel improvement.
The manuals and installation instructions were, um, challenging. I made the teams reengineer installers, UIs, workflows, whatever until the technical writing made sense. Other benefits included greatly reducing defects and technical support calls.
--
I also put the QA Test team members in charge of our releases. To great effect. Which I haven't seen any one else do before and since. But that's another story.
I only mention it to acknowledge that most orgs treat writers and testers like crap. Like you experienced. Which is unfortunate, wasteful, and rude.
I riffed on a notion from Ford's idea of quality circles, where engr, mfg, and QA made decisions jointly. And the USA Constitution's notion of balance of powers (trilemma).
My company was engineering driven. Our releases were always late. Way too many defects. QA/Test were demoralized. Sales and marketing weren't even part of the convo.
So I split responsibilities into three roles. Marketing determined feature set and price point. Engineering determined how and schedule. QA/Test controlled the release.
The first release cycle was VERY HARD. People hate change. I was an asshole and burned a lot of goodwill. Thereafter, our releases were always on time, we hit our P&L numbers, reduced our costs (eg tech support burden), and were given ever increasing amount of responsibility.
Later, I expanded the organizational triangle into a star by adding tech support, sales, and writing roles, each with their own responsibilities and authority.
We survived Y2K just fine. But 9/11 crashed our industry and we didn't survive not having customers.
Without real requirements how can anything ever be done? If nothing is done how do we get paid? If nothing is done and we have no money then what the fuck are you managing? Nearly every secretary or office assistant I’ve worked with has been more useful than the worst managers, and at less than half the salary. I have called this type of manager a glorified secretary before but that’s disrespectful to secretaries.
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.
Some highlights include defining your audience[1], engaging your audience[2] and reviewing how short and clear sentences improve comprehension[3].
1: https://developers.google.com/tech-writing/one/audience#defi...
2: https://developers.google.com/tech-writing/one/active-voice
3: https://developers.google.com/tech-writing/one/short-sentenc...
It is not a common word, I didn't know, and the way the GP included it was explanatory. Having "tenant" there would be very confusing, now, I just learned one more interesting.
In a post about writing, that's even on-topic.
> The course designers believe that you are probably comfortable with mathematics. Therefore, this unit begins with an equation:
> good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
> In other words, make sure your document provides the information your audience needs that your audience doesn't already have. Therefore, this unit explains how to do the following: ...
This is the kind of fluff that turns many people off. Worse, it is confusing and tries to make a formula out of a sentence. The whole thing could’ve been replaced with the first sentence of the 3rd paragraph I quoted.
Your reference 2 contains this gem:
> Short sentences communicate more powerfully than long sentences, and short sentences are usually easier to understand than long sentences.
And the section title immediately after that sentence is:
> Focus each sentence on a single idea
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.
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.
It also helps if the API or UI or whatever is logical and consistent to begin with.
My personal tips for writing docs: 1. think about what you need to get across and to whom. I've found this categorization helpful (just don't get religious about it): https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o... 2. try to say whatever you're saying with as few words as possible. "Vigorous writing is concise" is probably the best takeaway I got from Strunk & White (not a huge fan of the book otherwise) 3. do a few passes. "Keep rewriting" is probably the best takeaway I got from "On Writing Well" (but I like that book in general).
I read the course, there were three clicks setup and then I was choosing topics to read about. I did not get lost and it was short. None of that seemed overkill to me.
(To skip the podcast, scroll down the page to see the list of 10 tips)
https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/
The 'Writing for GOV.UK' guide is also full of good writing advice for people publishing content on the web:
https://www.gov.uk/guidance/content-design/writing-for-gov-u...
Good technical writing is much like teaching a great course: Empowering the reader to use the product or service for their own purposes.
The real challenge is that no one agrees what great writing really is or how to teach it. The problems are conceptual and related to the nature of writing, thinking, and communicating—all fields that are unsolved. I've taught writing in universities and written about the challenges of writing (and related grading challenges) before. https://jakeseliger.com/2014/12/20/subjectivity-in-writing-a...
"The big picture" is often the world itself.
I disagree that the big picture is so broad. Your article about subjectivity is accurate, but it applies to the field of creative writing. For technical writing and to some extent journalism, they are almost defined by by their purpose in communicating a specific thing. That “thing” is the big picture.
If the doc allows an average user to quickly setup the service and how to use it with two or three scenarios without getting confused is a good metric that the doc is good.
I'm going to check this out. But looking to Google for advice on docs is like looking to Google for advice on design and/or UX. You don't bother. There are higher quality sources of such info.
Yes. But this list is incomplete. In fact, it's missing the two essential questions the go into _any_ communication:
1) Who is the audience?
2) What do / don't they already know?
How you explain what they want to do is a direct funtion of you they are and their current knowledge toolbox (if you will).
The vast majority of tech docs suck because too often the sender assumes the receiver is just like them. That is, the sender fails to put themselves aside; fails to put themselves in the shoes of the receiver.
In my experience, all software has a purpose. For example, an API is for writing an app that gets and processes info from the server. That’s the big picture. The audience is someone writing that app. If they can’t write apps, it’s not the job of your doc to teach them. Aim the doc at the competent app-writer, give them useful info, and don’t add any fluff. In fact, if you provide a good API doc, it will teach beginners through good form and good examples.
the US Army writing style guide for leadership is also pretty good - https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/...
The examples here are very very good.
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: 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.
https://www.amazon.com/Presentation-Patterns-Techniques-Craf...
You can find it on the internet at various price points.
I even had a chance to give a technical presentation in front of the author and he said it was excellent, so apparently I internalized it’s lessons.
"torn" in this context means to be not decided between a couple of opinions or decisions.
https://inf.ethz.ch/personal/markusp/teaching/guides/guide-p...
He has a list of useful books at the end (I haven't read any of them, though)
The thing with most of the presentation books out there like Presentation Zen is that they're really oriented towards a good presenter up on a keynote stage at an event using slides as a supporting element of a well-rehearsed presentation.
That's not your typical presentation--and certainly not your typical internal monthly status meeting or project update.
Presentation Patterns also seems to do a better job than most at acknowledging the realities of material that's both presented and needs a leave behind. The "standard" advice is that you should have two separate documents but that's really not practical in a lot of circumstances.
I'm just like that. But I received wisdom from a friend that helped me a lot. The following "three" rules:
RULE 1. No bullet lists
RULE 2. No bullet lists
RULE 3. At least one meaningful image per slide, covering more than 50% of its surface
Then, you explain your subject like you would to a friend in a bar, keeping the slides as useful side material.
I found the video "How To Speak by Patrick Winston" delivered to new MIT students to be very helpful:
https://www.youtube.com/watch?v=Unzc731iCUY
Careful - once you become attuned to pp failures you will have little tolerance for them from both other people and yourself, and good presentations are a lot of work!
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 bringing along the audience, e.g., in what appears to be relatively technical content for movie audiences, the movies Star Wars. So, e.g., anticipate the audience reaction enough to see that they won't get lost and give up.
But let's set aside belle lettre, courses in "creative writing", etc. and move on:
It turns out there are some technical fields that have long had essentially their own techniques 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:
o The original Kemeny-Kurtz documentation on their programming language Basic.
o McCracken's documentation of Fortran.
o Any of the freshman college physics books by Sears, et al..
o Any of the best freshman college calculus books.
o IMHO, D. Knuth's The Art of Computer Programming.
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 writing style, technique of some of the homework. For a student who was taught writing Belle Lettre where often ambiguity is desired and precision is not, an abstract algebra course can be a good step forward for technical writing.
> "But they’re from the factory," John says.
> "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."
> They all look surprised. "I might have known," DeWeese says.
I’ve found writing in the vernacular is usually the most effective approach (speaking only for myself -YMMV).
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).
But this is a cool resource.
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.
If I’m speculating or unsure, I’m careful to note that.
Mild humor helps, but I need to be extremely careful, and it’s usually self-deprecating.
I believe part of the problem is also the font. Roboto is okay for a user interface. For prose I prefer serif.
My favorite page layout: http://www.linfo.org/
Update: I see it works in Chrome but not in Firefox. Not sure why.
So if the API changes, the example code in the documentation will fail to compile.
[1] https://doc.rust-lang.org/rustdoc/documentation-tests.html
It allows you to write Unit Tests using JSDoc
It won't necessarily stop your documentation from building but offers another good reason to document your code
Some devs will take interest to documentation but most wont. Most seem to just do a single mind-dump and call it good, no better than the college essay they got a C on. There's also real value in having someone own the organization of the writing.
Maybe a bit over-simplified: SW-Devs talk to the machines, Doc-writers talk to the people. If you can't make the machines understand what you want it to do, you fail. If you can't make the people understand what to do with your precious developed system, you fail.
If you're on a narrow format it looks like that table of contents is set into the top of the article below the lesson title.