Hacker News Reader

Comment by sixhobbits | Hacker News Reader

I run a technical writing business and all of our writers are engineers, so helping engineers improve their writing is a large part of what I do.

Unfortunately, there's no silver bullet. Writing is like coding. You get better by doing it. There are no shortcuts. Write. A. Lot.

That said, as long as you are writing a lot (and many people will read the next part and try skipping the previous one), we do have some resources that help at [0].

We also ran a writing course a few times [1]. We have no immediate plans to run another cohort - in general we got very positive feedback but participants just weren't able to commit the time to practicing, and that is really the most important part. Happy to run it again, or a version of it, if you have a few people who would find it valuable and have time to commit. Details in profile.

[0] https://ritza.co/handbook/improving-your-writing/how-do-I-be...

[1] https://styleguide.ritza.co/writing-course/

View on HN

This is basically what I did & do with my team. It requires you have someone who is already excellent at technical writing.

Document the principles of what makes good technical writing for your team.

Then you assign people on the team to document/write something, and have the person who is good at it edit their writing and discuss the changes in the framework of the principles you documented.

Lotta room for this to go wrong, maybe the person you thought was good at technical writing isn't that good, or can't communicate well. Maybe a lot of people on your team lack the language skills to do a good job. Maybe they don't understand things well enough themselves to communicate to others.

But in my case I was able to get 2 out of the 7 people who never really wrote to be good enough I'm proud to have them represent my team, which was a tremendous improvement.

>It requires you have someone who is already excellent at technical writing.

100%. You can probably help everyone on the team (to some degree) who is willing to do some work to improve. But you probably want one (or ideally two) people who can work with people and are the gate to actually publishing anything. They don't need to be a dedicated resource and don't even need to be "professional" editors. But they do need to be able to work with people and have strong writing (and copyedit) skills.

I would add that teams also need to commit to reading a lot, and to regularly editing what was previously written.

Writing in a culture where the written word doesn't have an impact, or where documents are skimmed once and go to die, is frustrating and will discourage people from trying.

I don't find writing to be difficult, but I do find getting started to be hard. My technical writing could be so much better if I had a template to choose from. The template would have all the headings and subheadings to get started.

Some examples of what I'm looking for might include:

* App/repo documentation for other developers to onboard (plus high level specs)

* Specific feature documentation and migration plan

* Technical post mortem documentation for a particular issue (focusing more on the technicals than a post mortem for management)

It sounds like you are running into the same problem that I did, which is that I wanted a structure to fill out with info. Don't do that. IMO, it's the hardest possible way to go about writing anything non-trivial.

Start writing in the middle of some random section in the middle of whatever you're trying to write. Jump around to different parts of the work if you get stuck. Edit it together at the end. You do not have to write from beginning to end in the same way that you don't sit down and write code from top to bottom.

If you really need a prompt, resist the urge to create a hierarchy of headers to just fill out. Writing is not just filling out a form. Try brainstorming a list of questions that your writing needs to answer. This has the added benefit of being able to divide up the work: you just give other people specific questions to answer. Let them organize the writing how it makes the most sense.

"Writing is like coding. You get better by doing it. There are no shortcuts. Write. A. Lot."

I disagree. You don't get better at something by just doing it a lot. You get better by doing something, evaluating how well you did (on a short feedback loop), then repeat a lot. Just doing and hoping that somehow you'll automatically evolve in the right direction won't get you anywhere. Coding implicitly has such a feedback loop. At the most basic level, your compiler will tell you about syntax. At a slightly higher level, you can see if your code does what you think it does. At a higher level still, in a matter of weeks or months you'll find out about your design decisions and architecture skills.

When writing, you don't get any such feedback. If you're very lucky and you write on quite straightforward topics like API docs, you can ask your readers 'did you get from this what you needed'. For anything more abstract, your readers most likely are not even qualified to assess how good your writing is. Overall, I strongly disagree with your notion that you should just start writing a lot and hoping for the best.

Well I didn't say "just write and hope for the best" and I agree with you to some extent, but most people will read books on writing, or follow frameworks, or watch videos, and not actually write.

Writing a lot and working with an editor and reading well-written works, and reading books on writing are all good for improving your writing. But if you have to pick one, pick writing. Most people pick all the others and skip the writing part.

Speaking as a sometime professional tech writer, your advice is good.

The best way I know to get rapidly better at technical writing is to write a lot with ongoing feedback from a capable professional editor. A good editor will teach you to catch and correct mistakes that you never knew were mistakes. Moreover, they'll teach you to understand why they're mistakes.

Unfortunately, the opportunity to write with the support of a capable technical editor is hard to come by. If you aren't working as a tech writer in a professional publications department somewhere, it might never happen.

Thank you! This is helpful

Reply on news.ycombinator.com