[HN Gopher] Technical Writing Courses from Google
___________________________________________________________________
Technical Writing Courses from Google
Author : sebnun
Score : 132 points
Date : 2022-08-08 19:05 UTC (3 hours ago)
(HTM) web link (developers.google.com)
(TXT) w3m dump (developers.google.com)
| kinow wrote:
| I am updatijg the user guide for an open source project, and
| found these short courses really helpful. It helps you write
| concisely and to keep the content simple. As well as provide some
| tools for structuring your docs.
|
| The other resources I used were Diataxis [1] and writing books I
| had on my bookshelf (Stephen King, Zinsser, etc)
|
| [1] https://diataxis.fr/
| photochemsyn wrote:
| I wouldn't rely on Google to learn good practices for technical
| documentation (unless they want to release their complete
| internal technical documents on how their recommendation
| algorithms work, that is).
|
| Instead, check out a reliable open source project like SQLITE,
| they have great documentation:
|
| https://www.sqlite.org/arch.html
|
| https://github.com/sqlite/sqlite
| CraigJPerry wrote:
| A while back i took both modules, they don't take long to go
| through. Module 1 wasn't any value to me, it felt far far too
| basic, i was really caught off guard by how basic it is. Module 2
| was ok-ish. The lasting change these courses left in me was more
| appreciation for investing time and effort into illustrations.
|
| I found other resources to be more impactful for me personally
| (e.g. jacobian / i'd rather be writing).
|
| I liked this model https://documentation.divio.com/ - agreeing
| with people what purpose the docs they're writing are for is a
| big chunk of the problem surface area. Having a model makes life
| easier. I'm not sure it has to be this exact model but this one
| seems good enough to me.
|
| A counterproductive tendency I've observed frequently is when an
| SME is tasked with documenting their thing and they go off in
| ELI5 mode. So tutorial instead of how-to per the above model.
| Having that model helps keep those conversations short and
| productive.
| mikedouglas wrote:
| I've heard Google uses design docs pretty extensively for
| internal projects. Does anyone have a publicly shared example?
| ruuda wrote:
| There are many public ones on chromium-dev and blink-dev, e.g.
| https://docs.google.com/document/d/1OjZoHNvn_vz6bhyww68B_KZB...
| linked from https://groups.google.com/a/chromium.org/g/blink-
| dev/c/POCUb.... (This is just the first one I found, I don't
| know if it's well-written.)
| mikewarot wrote:
| In other courses, Google talks about recruiting from the graduate
| pool, perhaps they need some technical writers and this is a way
| for them to hire at lower cost?
| more_corn wrote:
| Ha! Google is the absolute worst entity to teach technical
| writing. Go read some of the documentation for google cloud. Pick
| any single thing you might need to do to stand up a new service.
| I guarantee you'll be disappointed.
| 6ue7nNMEEbHcM wrote:
| Or you could just take a look at the linked course and learn
| something. It's pretty good and worth working through.
| arccy wrote:
| I find cloud documentation to be pretty clear most of the time
| danesparza wrote:
| Normally, I love free resources like this. I don't mean to throw
| shade at Google... but can anybody tell me if there is a set of
| documentation that Google has created that you would hold up as a
| standard that you would personally like to match? I can't think
| of anything. I really think Google needs to get a lot better at
| documentation before they start passing out classes like this.
| gresrun wrote:
| Dart's documentation is comprehensive, well-written, and
| provides tons of meaningful examples.[0].
|
| [0]: https://dart.dev/guides
| bencorman wrote:
| Flutter's documentation is fantastic. A lot of effort went into
| it, and it shows.
| clumsysmurf wrote:
| Speaking for Android, the guides are pretty good, but the
| references from javadoc are abysmal. I wonder how much of this
| is because of scaling flaws in javadoc tooling for usage over
| such a large code base. But, in some cases, its clear because
| there are no javadocs at all (can't blame the tools for that!)
| gundmc wrote:
| I've found the GCP documents well-written and nicely
| structured, at least around cloud storage and pubsub.
| MonkeyMalarky wrote:
| I find GCP documentation to be very bipolar. It's either
| spartan and terse, or almost overwhelmingly too much. In the
| latter category, sometimes it's like the getting started
| article for one topic links to more and more until all of a
| sudden you've got 20 tabs open.
| ColanR wrote:
| Far as their public stuff goes, I'd tend to agree with you. If
| the OpenBSD folks published a course like this, though...
| rickette wrote:
| Angular docs are pretty good. Also didn't have trouble with GCP
| docs.
| trebbble wrote:
| Android's developer docs are the only ones from Google I've
| used extensively enough to have an opinion on them, and that
| not in the last three years or so, but those spent at least a
| decade being notably poor.
| edmundsauto wrote:
| I disagree - the advice can be top notch independent of
| Google's organization successes. Teaching individuals still has
| value, because nobody is born a great writer.
|
| Google's failure could be because the org is not incentivizing
| good documentation.
| [deleted]
| maxerickson wrote:
| It's got issues. Like the use of the word "develop" for the
| clear and short sentence strategies on this page:
|
| https://developers.google.com/tech-writing/one
|
| Utilize and employ are about the same level of obscurity as
| 'develop' and much closer to the intended meaning.
|
| A later inspirational message is very impressed with itself:
|
| https://developers.google.com/tech-writing/one/paragraphs
|
| The work of technical writing is to organize and clearly
| present information.
|
| I wouldn't pat myself on the back if I published a writing
| guide that was easy to nit pick.
| joshuamorton wrote:
| The goal of something and the work of something are
| distinct. Untangling a topic is work done in service of,
| ultimately, clearly presenting information.
|
| The guide appears correct, and your criticism misplaced.
| User23 wrote:
| The Go documentation is high quality.
| _the_inflator wrote:
| This is great stuff. Resemblance with academia and academic
| writing is recognizable.
|
| However, I would have expected more tools to guide the process.
| NLP tools instead of writing exercises here and there.
| itake wrote:
| Did you take the course? I saw on an HN thread mixed reviews.
| ruuda wrote:
| This course is great. I took it in person a few years ago, and
| I've since recommended it to quite a few people who got
| noticeably better at technical writing afterwards. There is not
| any great eye-opening insight in the course, it's mostly good
| practices you already knew anyway, but it's very useful to be
| reminded of them, and have them spelled out clearly in one place.
| molodec wrote:
| I am not a native English speaker. I could never understand the
| stress on active voice. "The vast majority of sentences in
| technical writing should be in active voice".
| https://developers.google.com/tech-writing/one/active-voice This
| is stated as an axiom without any explanation.
| netr0ute wrote:
| Here's why you should use the active voice:
|
| 1. It lets you know who/what is performing the action, instead
| of leaving it to the reader to figure it out.
|
| 2. It makes the writing less repetitive because each
| descriptive word becomes a verb, instead of "to be" being in
| every sentence.
| buzzy_hacker wrote:
| Active voice is usually more clear, tight, and pleasant to
| read.
| karlmdavis wrote:
| "We are raising your plan's rates."
|
| versus:
|
| "The plan's rates have gone up."
| kazinator wrote:
| The active voice removes the information about what agent is
| responsible for the action, which has the effect of removing
| clarity. The reader would like to understand cause-effect
| chains, whereas the passive sentences indicate that certain
| actions happen, as if spontaneously.
|
| Passive sentences are used in blame-deflecting language, such
| as statements that superficially look like apologies, but don't
| indicate who is at fault, and so do not indicate any acceptance
| of responsibility.
| beezlebroxxxxxx wrote:
| In technical writing, which is often trying to be as concise as
| possible, active voice usually allows the shortest sentences,
| which, as a practice, tend to be more clear.
|
| However, there are instances when the passive voice is
| important and should be used. For instance, if you are trying
| to put an emphasis on the fact that a subject receives an
| action. This can often be done in a passively voiced sentence
| where you clarify a certain relationship. In other words,
| passive voice can be an important part of adding context.
|
| The idea that you should _never_ use passive is largely just
| people hearing a rule and thinking it is the end all be all. In
| reality, you 're better off learning what both types of
| structure do, and then choosing one or the other with a
| specific goal in mind.
___________________________________________________________________
(page generated 2022-08-08 23:00 UTC)