
Technical Writing Courses - Lilian_Lee
https://developers.google.com/tech-writing
======
breckenedge
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.

~~~
hnarn
Your comment makes me think that writing primary documentation should always
be the job of developers, with time dedicated for the task, and technical
writers can do the polishing and categorization that will likely be necessary
for it to be published. Being the only one responsible for documentation while
not being a developer must be a nightmare.

~~~
CraigJPerry
Yeah in practice there’s just no other way in the places I’ve worked. The
problem I’ve encountered still though is getting developers to estimate
sufficiently to give that time. Developers massively underestimate (myself
included).

~~~
Viliam1234
If you have waterfall, there is usually not enough time to make the product
itself, and documentation is much lower priority than that.

If you have agile, in theory all developers are replaceable. In reality, a few
have writing skills, but most don't.

------
mattlutze
After reading some of the comments here, I'm wondering if people are actually
following the link and reviewing the content.

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...](https://developers.google.com/tech-
writing/one/audience#define_your_audience)

2: [https://developers.google.com/tech-writing/one/active-
voice](https://developers.google.com/tech-writing/one/active-voice)

3: [https://developers.google.com/tech-writing/one/short-
sentenc...](https://developers.google.com/tech-writing/one/short-sentences)

~~~
205guy
Your reference 1 is a deep-link that skips the intro. The intro says:

> 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

~~~
lonelappde
Maybe that's the point? Education through irony?

------
205guy
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.

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.

~~~
jseliger
_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._

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...](https://jakeseliger.com/2014/12/20/subjectivity-in-writing-
and-evaluating-writing/)

"The big picture" is often the world itself.

~~~
205guy
I do agree that writing is a moving target. Different people learn in
different ways, some people learn best from the style and content in the
original submission. I’ve often thought that all docs should have a mirror
video tutorial to give the same info for visual learners.

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.

------
sandGorgon
The best i have seen is the economist style guide - [http://cdn.static-
economist.com/sites/default/files/pdfs/sty...](http://cdn.static-
economist.com/sites/default/files/pdfs/style_guide_12.pdf)

the US Army writing style guide for leadership is also pretty good -
[https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/...](https://www.esd.whs.mil/Portals/54/Documents/DD/iss_process/Writing_Style_Guide.pdf)

The examples here are very very good.

------
Too
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.

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._

~~~
ghaff
To be honest, that's a problem with a lot of in-person workshops and the like
as well. There's a lot of type this, type that, run this script, etc. without
enough context as to why you're doing these various steps.

~~~
ntsplnkv2
Yep - so many workshops could simply be a list of steps to do X. But often
times the real world isn't that simple, and then the workshops are essentially
worthless. With an understanding of how something works, I can apply it to
more scenarios, or modify it to fit more scenarios. This is often woefully
lacking in modern training/documentation.

------
noisy_boy
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).

------
daxfohl
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.

~~~
jedberg
This book completely changed how I give presentations.

[https://www.amazon.com/Presentation-Patterns-Techniques-
Craf...](https://www.amazon.com/Presentation-Patterns-Techniques-Crafting-
Presentations/dp/0321820800/ref=nodl_)

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.

~~~
riedel
I am a bit torn apart reading into it and watching a presentation by him. I
think it might work well in some cultures and with some speakers. Being at a
university seeing a lot of technical presentation by students I think he is
quite heavy on presentations, which I typically always suggest to use really
carefully my students and inexperienced speakers.

~~~
emmelaich
just "torn" not "torn apart" \-- which is quite a violent thing!

"torn" in this context means to be not decided between a couple of opinions or
decisions.

------
graycat
Teaching of _writing_ has long been mostly about teaching how to write _belle
lettre_.

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.

------
wallstprog
From "Zen and the Art of Motorcyle Maintenance"
([https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-R...](https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-
RobertPirsig/mode/2up))

> "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.

------
ChrisMarshallNY
I’ve been writing my entire life.

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.

------
combatentropy
Page layout matters, and Google's has become cluttered. For example,
[https://cloud.google.com/sql/docs/postgres/private-
ip](https://cloud.google.com/sql/docs/postgres/private-ip) 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.

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/](http://www.linfo.org/)

------
Aeolun
I want something like this but for Business Architects on how to write their
requirements (and conversely, how not write the requirements)

------
aliabd
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: [https://trymaniac.com](https://trymaniac.com)

~~~
j88439h84
I want diagrams of my modules and how things are connected, such as one that
shows "types defined in foo.py are used in bar.py". While you're generating
docs from code, might think about diagrams.

~~~
aliabd
That's actually really dope, thanks! I bet we could do something there...

------
polcia
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?

~~~
therealdrag0
I think it is an area of work that (given a large enough company) benefits
from having dedicated owners. Engineers have too many other things pulling at
their strings, whether it's deadlines or just code they 'rather' be working
on.

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.

------
boojing
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.

~~~
yihsiu
I actually prefer the way it is. When there are too many links around, I tend
to do some DFS-like reading and it ends up anxiety and tons of tabs. Things
get worst when there're loops.

