by maxekman on 6/24/22, 8:23 AM with 158 comments
I have a fairly strong background in cloud system and application architecture. However I feel that I’m sometimes limited by my technical writing skills to communicate my ideas and concepts. Any advice on how to take ones technical writing skills to the next level?
I’m willing to do what it takes, being online courses, contributing to OSS process work or what else you might suggest.
Looking forward to tap into the HN hive mind on this topic!
Thanks, Max
by marcpaq on 6/25/22, 10:54 AM
The absolute, invariable first rule in tech writing is to know your audience.
Understand not just their technical problems but take the time to empathize with why they have these problems in the first place.
Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems.
Oh, and use an editor (the human kind, not the digital kind.)
by Gaessaki on 6/25/22, 2:58 PM
Personally, my process after this is to express my thoughts in bullet points, followed by inserting any placeholders and captions for any graphics (e.g. charts or diagrams), and then finally I start rewriting my bullet points into proper sentences, expanding my examples, and adding any interstitial text necessary to make things flow.
Also, I see some comments on keeping things short and to the point. In general, I agree with this, but depending on the medium, sometimes it doesn’t hurt to inject a bit of personality into your writing. Technical writing can be dry at times, and this can deter engagement. Try to use concrete examples whenever possible or refer to other supporting texts.
by gnat on 6/25/22, 1:39 AM
And "Bugs in Writing", which I've been pressing into people's hands for twenty years now. https://www.amazon.com/BUGS-Writing-Revised-Guide-Debugging/...
by mishftw on 6/25/22, 2:03 PM
I have realized that written/technical communication is a great differentiator.
I journal every day but specifically to your question I would say just start writing.
Knowing your audience is key. I usually include an executive summary section at the top of any design document or product requirements document for a high level view of why people should care. Then I dive into a background or history to give context. At the end of the day it's a narrative and follows similar arcs - just with more direct prose and specific facts. I'll also drop this resource here from the Pragmatic Engineer newsletter. [0]
[0]: https://newsletter.pragmaticengineer.com/p/software-engineer...
by MrPowers on 6/25/22, 12:14 PM
Improving open source project READMEs and documentation is another great way to practice writing.
I am writing an O'Reilly book now and having a professional editor will help you learn the common errors you're making.
You should try to write short paragraphs, short sentences, and at a 4th-6th grade reading level. Good writing for literature is a lot different that good technical writing.
A good novelist may write at a 12th grade reading level, may use complicated words, and will use literary devices like allegory and foreshadowing.
A good technical writer should explain a concept in the most simple way possible. They should explicitly avoid literary devices like foreshadowing - their goal is to explain the concept in a straightforward manner. They should also avoid big words and long sentences. A large portion of technical readers are not native English speakers, so only the most basic words should be used.
by Tomte on 6/24/22, 9:01 AM
Joseph M. Williams, Style: Ten Lessons in Clarity and Grace.
An old edition is fine. There are many editions with slightly differing titles (Toward Clarity and Grace, The Basics of Clarity and Grace), all of them are fine. Get the cheapest or fastest to deliver or whatever. Don't think about which one to get.
The other great book about writing is Thomas&Turner's Clear and Simple as the Truth. It teaches Classical Style, which is less fitting to technical documentation, as the authors discuss themselves.
by sateesh on 6/25/22, 11:05 AM
by kashyapc on 6/25/22, 11:04 AM
Be prepared for several rounds of fine-grained heavy editing process. FWIW, I benefited greatly from my interaction with the LWN editors by contributing a handful of articles. Here's a somewhat recent example[2].
[1] https://lwn.net/op/AuthorGuide.lwn
[2] "A QEMU case study in grappling with software complexity" — https://lwn.net/Articles/872321/
by DonHopkins on 6/25/22, 9:42 AM
It's a much better experience and result than reading on a screen, editing it while you're reading, getting distracted, jumping back and forth between doing other things.
by eatonphil on 6/25/22, 1:13 PM
I've been doing this for 1-3 blog posts per month for the last 4 years and I think my writing is decent now.
It didn't come naturally. I hated editing all my life until I took a course in college and realized I could actually write clearly if I just spent a little time reading and reworking what I wrote.
The only directly related book I'd recommend is On Writing Well.
I'd also suggest reading clear and simple authors like Hemingway (A Movable Feast), Antoine de Saint-Exupéry (Wind, Sand and Stars), and Beryl Markham (West with the Night).
But fundamentally: consistent practice, rereading, and editing.
by _sohan on 6/25/22, 4:12 PM
Before writing down a long form doc, make a quick mondmap answering the following:
1. What are the three core ideas you’re writing about? 2. What are the three main criticisms / counter arguments against your ideas? 3. How do you plan to respond to the criticisms?
Depending on the subject matter and length of the doc, you may need more or less than three. But see if you can get this mind map written first. Then, see if you’re convinced the ideas are worthy of writing. Only then write the long form.
by phendrenad2 on 6/25/22, 3:01 AM
by O__________O on 6/25/22, 11:41 AM
Anyone looking for a good system of producing documentation should check out:
https://documentation.divio.com/
Which has a 30-min presentation:
https://m.youtube.com/watch?v=t4vKPhjcMZg
Prior HN posts on the system are here:
https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....
by DoreenMichele on 6/25/22, 2:01 PM
Benefits: You get prompt feedback as to the quality of your writing. You may build a reputation.
Downside: That feedback may not exactly be sugar coated.
by captainkrtek on 6/25/22, 3:32 PM
- why does a document need to be written? Is it to be discussed, debated, just documentation? Let this drive what really needs to be written. Often I’ve seen design documents with lengthy sections on information that is already well agreed upon or commonly understood, just adds noise for the reader.
- consider the audience. Engineers may read a document and have specific prior context that can be omitted, whereas a product manager may get lost in too much technical detail. Tailor your document to your audience, and use the appendix for extra details if someone wants to dig in further.
- keep it brief. Focus on information required to get the necessary outcome and convey the information clearly. Starting with an outline of headers is helpful as well.
- think of good writing you’ve come across. It was likely clear and succinct enough. In my own writing I used to include every last detail to make sure the reader was the most informed about how I reached some conclusion, but then realized too much info becomes counterproductive and doesn’t focus the reader on what matters.
by gautamdivgi on 6/25/22, 6:03 PM
One pesky little detail is that documents take a lot of thought to write and this translates into a good bit of time to get a document out for review. If you have a "how fast are you closing your JIRA tickets" manager, it can be hard to justify and will come back to bite you (unfairly so, but such is the life of a sw. engineer).
by asicsp on 6/24/22, 10:18 AM
Here's some technical writing courses: https://developers.google.com/tech-writing
And here are some examples of good writing: https://news.ycombinator.com/item?id=31630915
by klodolph on 6/25/22, 12:18 PM
In technical writing, clarity reigns. Clarity above all else. Lists? Use bullet points. Topics? Make headings. Do two terms seem similar? Change your wording to make the differences obvious. Is there a technical term? Use it consistently. Are you using the same word in different senses? Use two different words. Using negatives? Use positives instead, they are easier to parse.
If you are good at the details of writing, your thoughts and ideas become clearer, because clear writing exposes the flaws in your ideas.
Recommended book: Style: Lessons in Clarity and Grace.
I also recommend finding a topic to blog about. You don't need to be an expert. Just keeping an active blog teaches you a lot about writing.
by inphovore on 6/24/22, 9:08 AM
The most effective way to improve your writing is through improving your reading.
I’m a literary nerd as well as a technologist, and will tell you it’s easy to spot an English Lit graduate by their universally good documentation skills. Not because they use fancy words, or exotic expressions, because they use simple deadpan and well measured (never crowded) sentences. These tend to always write as though they’re explaining to an intelligent child (with a pleasant unassuming and direct simplicity.)
by christophilus on 6/25/22, 12:52 PM
Pick a product/ technology you’re familiar with and which has great documentation.
Go to their docs, and pick a page that is on a topic you know well.
Read only the title of the page.
Write the documentation.
When you’re done, compare your results with theirs. What headings did you choose vs theirs? Why do you think they chose the ones they did? How does your document flow vs theirs? How’d they illustrate the concepts vs you?
It’s an informative and fun exercise, at least to me.
by ericmay on 6/25/22, 12:31 AM
It’s no different than writing code or writing a book. It takes time, iteration, and focus.
Personally happy to review a doc or two and provide feedback if that is helpful. I run a docs site for my company.
by larsrc on 6/25/22, 2:28 PM
Write on paper first.
Paper is more immediate and has fewer distractions, fewer ways to go back and edit at once, and leaves a bit more time to think. It doesn't require looking at a screen, which you probably do enough of already.
Sure, typing it up is an extra step, but it can be a good editing step. Having edited (to the best of my ability) some of my wife's writings, I have been able to correctly guess when she wrote directly into the computer simply by the writing being less coherent.
by edding4500 on 6/25/22, 12:09 PM
by SKILNER on 6/25/22, 4:52 PM
Our brains only have so much space in them so you only get to cram a small number of words into someone else's brain; make them the most productive words possible.
When writing, it's harder to remove words than write them.
by dmitriid on 6/25/22, 10:55 AM
When writing about a concept, or a system, do something like
---
This system consists of
- A
- B
- C, (but see notes on C below)
(and then do the same for C further down)
---
Label each section with a header and have a ToC that has every header in it.
All this will let you do two things:
- cut down on bullshit, and be concise and precise.
- see and quickly change the structure of your document
by rawgabbit on 6/25/22, 5:33 PM
Get to the point. Usually in the first two paragraphs. The entire meat of a memo or chapter is on one page. The rest of the memo or chapter is supporting material with examples, clarifications, diagrams, and context showing how this idea relates to a different idea.
In meetings, I usually present only the first page or one diagram that summarizes the entire memo. I usually tell people to read the whole thing if they want more details.
I am also in the habit of sharing my drafts with a lot of people so they know what I am up to. By the time it’s completed the audience has probably already seen it twice . This helps with buy-in. As I have already met with people who have concerns or objections.
by fnord123 on 6/25/22, 10:51 AM
To some it will be too obvious. But English speakers (especially English as a second language people) outside the US have often never heard of it.
by benreesman on 6/25/22, 12:10 PM
I now regard it as a minimum bar that I can explain the broad outlines in plain language.
Anyone who can’t is is a fucking fraud.
by rozenmd on 6/24/22, 10:28 AM
by anon1094 on 6/25/22, 2:02 PM
1. Write more.
2. Write clearly.
3. Know your audience.
by pclmulqdq on 6/25/22, 1:20 PM
1. Write a white paper on the application of a piece of OSS that you like.
2. Write a usage description for one of your one-off projects/scripts.
3. Write a technical paper about an algorithm you used in a specific instance.
4. Explain the solutions to classic interview problems (eg binary tree reversal) in written form.
5. At work, write up brief pitches for new product improvements you have.
In all cases, consider the audience and what needs to come across to accomplish your goal.
by ayewo on 6/25/22, 5:53 PM
If you are up for it, you could try moonlighting as a writer for technical content marketing agencies. You get paid on the side, while also subjecting your writing to editorial criticism until it is ready for publication.
by coffeefirst on 6/25/22, 1:58 PM
Every type of writing you practice makes you better at every other kind of writing. The part of your brain that learns to make fiction flow will do the exact same thing for complex technical documents.
Also, find someone you think is amazing at technical writing and ask them to sit down with you and revise something you wrote. Study what they want to change and why.
by tetha on 6/25/22, 11:58 AM
by st00 on 6/25/22, 3:36 PM
https://developers.google.com/tech-writing
Originally, the material was targeted at SWEs, trying to give them pragmatic ways of thinking about the advice you'll read elsewhere in this thread. I haven't kept up with it, so I don't know if that's still the focus.
by sixhobbits on 6/25/22, 3:46 PM
I also keep a repository of my favourite books and some other resources here [1]
And some very short advice we give to our writers here [2]
[0] https://styleguide.ritza.co/writing-course/
[1] https://github.com/sixhobbits/technical-writing
[2] https://styleguide.ritza.co/improving-your-writing/how-do-I-...
by no_identd on 6/25/22, 5:45 PM
https://twitter.com/no_identd/status/1220913617408864257
Prompted by my discovery of this book:
https://link.springer.com/book/10.1007/978-3-030-10756-7 "A Math-Based Writing System for Engineers: Sentence Algebra & Document Algorithms", by Brad Henderson
Edit:
Altmetrics just revealed to me that apparently a cheesy corporate marketing video for it exists:
Amazing.
by yrui on 6/27/22, 3:32 PM
Books that influenced me:
Style, by F.L. Lucas
Simple and Direct, by Jacques Barzun
For technical writing, I recommend four additional disciplines:
1.) Keep the documentation up to date.
2.) Allow and encourage your readers to give you feedback about what's unclear. Then make revisions based on this. Also, re-read what you wrote periodically, and make revisions whereever you think you can improve clarity and usefulness.
3.) Provide copious examples where you show how to accomplish useful things.
4.) Use the tool you're documenting. Find errors, corner cases, and things to be aware of and document them as comprehensively as possible.
by coxley on 6/27/22, 4:37 PM
* On Writing Well
* Google's free, self-guided technical writing courses
Using these, you should get much better at refining your writing. Write naturally, then go back and edit when rereading according to the your new skills.
Another thing to get better at is layering your message. Assume that some percentage of people drop off each paragraph. Important details for the entire audience should be front and center. Then gradually get more specific.
Boz has a nice write up on this: https://boz.com/articles/communication-is-the-job
by delecti on 6/25/22, 4:35 PM
I also try to assume my audience is a moron. Not because they are, but because any time you're doing technical writing, you presumably know more than them. Force yourself to not assume things are obvious just because you're familiar with them. IMO it's better for technical writing to be a tiny bit patronizing than to be lacking in vital detail. One specific example here is to either define any acronym before using it, include a glossary, or both.
by warrenm on 6/27/22, 1:11 PM
>Communication is like selling - it's all about return on investment. And ROI is all based on understanding abstractions (and how they leak). You need to give the reader/listener enough of a promise they're going to get value at least proportional to the time spent consuming what you're trying to convey that they want to stick around.
by GeneT45 on 6/24/22, 3:44 PM
by Grimm665 on 6/25/22, 8:47 PM
I don't have a strong background in technical writing, but often get compliments on my documentation and the secret is org-mode; it makes writing structured documents easy, and there are many tool for converting org-mode docs to any format needed, so it adapts to any audience.
by teddyh on 6/25/22, 10:37 AM
by BurningFrog on 6/25/22, 2:45 PM
In writing, this manifests as not attempting to bring the reader up to speed with underlying concepts. Since they are "known". This can result in texts that only work as a reminder for those who already know the field.
I don't have a great way to "fix" that problem, but the first step is to at least be aware of it!
by danrl on 6/25/22, 1:42 PM
I found this guide helpful: https://www.knowledgeowl.com/home/three-tips-psychology-docu...
by 1970-01-01 on 6/25/22, 2:34 PM
by jacksnipe on 6/25/22, 3:25 PM
So make sure that things are motivated, and try to not just tell the reader the facts, but take them on a journey such that they will wind up with the right facts AND the right mental model at the end of things.
by sealeck on 6/25/22, 3:25 PM
- just write and then edit - better to have written something (even if it's not great) and then make it better. Especially in writing perfect can be the enemy of good.
- step away - sometimes it helps to review your writing after maybe 1 hour or a day or a few days
- READ MORE - reading well written stuff really helps
by teleforce on 6/26/22, 10:40 AM
Docs for Developers: An Engineer’s Field Guide to Technical Writing
by silasdb on 6/25/22, 7:50 PM
by quercusa on 6/25/22, 4:50 PM
by memling on 6/25/22, 5:25 PM
by Torwald on 6/25/22, 12:12 PM
by maxekman on 6/26/22, 8:31 PM
by dan-robertson on 6/25/22, 10:49 AM
by rleigh on 6/26/22, 8:35 PM
As the top poster mentioned, "know your audience". You must pitch your material at the right level for the reader. This doesn't mean dumbing it down. It means not including material which isn't relevant for the discussion at hand, and including material which is relevant. As an example, in some internal documentation for end users, one programmer wrote up details about the I2C bus number and addresses and details of some parts on the bus. Not suitable for user documentation, it's just not relevant at that level. They could have mentioned what the user needed to know e.g. configurable options within the application and their effects upon the device function and behaviour. That could be quite detailed, but it doesn't need to include unnecessary detail about the hardware details.
Structure your documentation to introduce concepts that build on each other in order.
For each topic, write an introduction to provide an overview of the concepts and what you will cover, then go into details with examples in logical order, and then wrap it up with a summary and any relevant conclusions at the end. You're taking the reader on a journey with you through some complex topic and you need to treat it like a story with a narrative. It all needs to fit together as a whole, not just a collection of disjoint factoids.
Have a read through various technical books and see how others structure their writing. See how they break everything down into (volumes!), chapters, sections, subsections and paragraphs, and then look at how you can take the system you are documenting, and break it down in a similar way. In many ways this mirrors breaking down a complex set of requirements into applications, libraries, data structures and functions, and depending upon what you're writing about there may be some commonality there. But you aren't just describing the nuts and bolts, you're describing the whole system, conceptually how it is designed and all fits together as a whole, how it's intended to be used, and bring it together in a logical sequence.
Also, look at effective use of figures and tables. With a few good drawings, even very simple diagrams, you can use them to frame what you'll cover in the text. Likewise with tables, don't write out longhand what can be summarised in tabular form.
Just like doing presentations, effective writing comes with practice. And help with review and proofreading will help greatly to spot and improve weak areas. I was lucky to work with a technical writer in my previous job, and she greatly improved the writing technique of many of the software developers on our team. It's a shame that it's not highly prized in software development, because it's an essential tool for effective communication of ideas, and it's a big part of what we should be delivering to our end users and other developers.
by juskrey on 6/25/22, 1:27 PM
by xena on 6/25/22, 1:23 PM