Hacker News new | past | comments | ask | show | jobs | submit login
Technical Writing Courses (developers.google.com)
563 points by Lilian_Lee 8 days ago | hide | past | web | favorite | 73 comments





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.

Twice I’ve seen a tech writer turn into de facto project manager because the real manager was asleep at the wheel.

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.


PHB (Pointy Haired Boss) is a recognized expression in some circles.

https://en.wikipedia.org/wiki/Pointy-haired_Boss


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.

I’ve noticed the master software engineers around me tend to have a particular acute sense for naming things, as if after living with and mastering the universe of abstractions around their craft they’ve embraced the linguistic dimension of the work, minimizing cognitive load and aligning execution with intent.

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.


Naming tings is so important. Even more so if you know you will not have time the document properly. Typical sign that someone did not take the time to name : utils, shared or misc ...

Seen it so many time in poor quality project. Hardly ever in project that have a high quality bar set.


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

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.


The problem is that you are estimating instead of producing and measuring. Just take the time and succeed or fail. Don't estimate it

TLDR: Redesign the product until its description makes sense.

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’d love to hear more about the QA team managing releases- how did that go?

This was mid to late 90s. I don't know if execution would apply today. But the notions of designing the organization are evergreen.

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.


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

2: https://developers.google.com/tech-writing/one/active-voice

3: https://developers.google.com/tech-writing/one/short-sentenc...


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


Maybe that's the point? Education through irony?

tenets, not tenants.

added a lot of value there

pdr2020’s spelling-correcting comment indeed didn’t add much value, but as it was three words long, it also used up very little time and attention. I think such spelling-correcting comments don’t deserve the criticism you implied. The (minor) benefit of preventing mattlutze from making that particular spelling error in the future was well worth the (minor) effort of making them read a three-word comment.

For me, a non-native English speaker, it added value.

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.


Alright, I stand corrected.

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.


To me as someone often reads documentation, the lack things outlined in that course make it harder. Not defining terms before using is something I sweared about a lot. Documentations with long complicated sentences are hard to follow.

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.


Related are the atrocious user manuals and tutorials for various consumer electronics products. You get descriptions like "if the self-diagnostic tool shows the message 'no errors found', it means that there are no errors that the self-diagnostic can see." Or other manuals or help texts that just plain rephrase the prompt.

Good technical writing is much like teaching a great course: Empowering the reader to use the product or service for their own purposes.


Great comment about missing the forest from the trees. The course outline reminds me of an article on "writing great code" that lists the rules of a code formatter.

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


The trick to writing that works for me is to combine tips 2 and 3 iteratively. I don’t write concisely at first (and I think that’s the case for most people), so I just write down everything I can think of related to the topic, even all the edge cases. Then I go back and simplify, maybe focus on a relevant example. I cut out fluff and stick to that example, perhaps with the list of edge cases in a separate section (and call it “Advanced Use Cases”).

I like these 10 tips for clear writing from the GOV.UK team. The tips can be used by anyone to help their writing and are not specific to technical writing.

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


Perhaps their newer products have gotten better but I've traditionally found Google's documentation to be case studies in how _not_ to write docs. Typically, they seem to be writen for ppl who understand the product and/or situation. You know, the type of ppl who don't need the docs.

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.


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

"The big picture" is often the world itself.


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.


> The real challenge is that no one agrees what great writing really is or how to teach it.

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.


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

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.


Those are the trees I was talking about. Actually, 1) is subsumed by “what the reader wants to do,” and 2) is unknowable and you’ll write a hard-to-use doc covering all the cases (kinda like the original submission).

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.


Really interesting comment thanks! Do you have any more tips for improving in technical writing? Do you know of any other good book / course on this matter?

The best i have seen is the economist style guide - http://cdn.static-economist.com/sites/default/files/pdfs/sty...

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.


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.


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.

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.

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.

This book completely changed how I give presentations.

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.


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.

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.


> But when manager is like "can you create a couple slides about...." total deer in the headlights.

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.


Presentation Patterns, which a couple of people have mentioned, is probably more practical than most in terms of giving bite-sized advice though a lot of it is overkill (and not really even appropriate) for giving a manager a couple of slides about something.

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.


Myabe your anxiety is because you're focusing on the "make some slides" vs. "deliver content in a presentation format". If you adhere to guidance for the later the slides are actually pretty easy. You quickly release they are just a prop that supplements the entire production.

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!


I've attended several short courses on giving presentations. This one by an ETH Zurich professor is the best one I know of:

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)


Do you find the problem to be more around design or story telling?

Both, really. Maybe one driven by the other. I think of what I want to say, try to find a template, no template quite matches, pick one reasonably close, get bogged down by colors of arrows and things not snapping right, wonder if what I'm trying to say is no good or else there would be a good template already, start over in Visio, same process back to powerpoint.

I know right.. Any similar resources for this?

See my sibling reply.

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.


From "Zen and the Art of Motorcyle Maintenance" (https://archive.org/details/ZenAndTheArtOfMotorcycleRepair-R...)

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


Page layout matters, and Google's has become cluttered. For example, 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/


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.


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

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?

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.


I am very happy with (technical writing) experts helping with their expertise. That is how I want culture to see their role.

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.


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

This is something that I’ve felt is going to become very hot - some way of ensuring that documentation never goes stale. In the same vein as tests needing to pass before merging a commit, ensuring documentation is up to date when commiting. Looking forward to hearing more!

Rust has a feature that somewhat provides this - doctests[1]. Rust doc comments begin with `///` and will be parsed as markdown when generating documentation. If there are codeblocks in the documentation comments, they will be run with all other tests and the test runner will report if the blocks fail to compile or if they error at runtime.

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


For anyone looking for something similar with JS, we wrote doctest-js: https://github.com/supabase/doctest-js

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


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.

Have you tried Pyreverse[1]? I used it for my Software Engineering course. From the documentation - Pyreverse analyses Python code and extracts UML class diagrams and package dependencies.

[1] https://www.logilab.org/blogentry/6883


I'm pretty sure Doxygen does that (http://doxygen.nl).I used to use it all the time, but I use Jazzy, these days, and Jazzy does not do it.

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

The staggered screenshots that are ostensibly examples are all blank?

Update: I see it works in Chrome but not in Firefox. Not sure why.


Not sure either but will fix, thanks!

Whoa.

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.

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.

There's a lesson overview on the left-side navigation, and an inner-lesson table of contents on the right-side navigation, which links to each topic or learning objective.

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.


I found that turning my tablet sideways revealed a sidebar with links to each section of the courses. Sometimes responsive UI is not better.



Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: