91–100 of 162 posts
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.
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-...
A few pointers from my own experience (usually in the context of design or proposals): - 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. Enginee…
And I'd add to that: Be reasonably consistent. Don't be belaboring what a microprocessor is and what it does in one sentence. And then throwing around jargon like registers, branch prediction, and hyperhtreading in the next without any explanation.
One thing I miss writing for the web is that footnotes don't work very well. When I was writing research notes, I really liked footnotes for--among other things--providing some parenthetical detail about technical terms and the like in a way that didn't break up the flow. Unfortunately, on the web, footnotes generally break up the flow more than just adding the detail inline.
Earlier quoted context omitted.
> It's really hard to find fiction books, that are less than 500 pages. For SF & F this seems to be a deliberate choice, from what I understand. This is from an iterview with Ted Chiang: TC: I think the reaction varies, because science fiction is a more commercial genre. There are a lot more people in science fiction whose goal is to make a living from writing fiction by publishing one or more novels a year. And peop…
While I see where you’re coming from re: The Three Body Problem Vs the rest of the series, the core ideas in the Dark Forest and Deaths End are so exciting that I can’t help but feel the rest of the story is a justification for exploring them.
When I left high school for college (to pursue engineering) I was quite envious of my friends in the liberal arts - they were assigned papers all the time and I had no outlet for writing (something I enjoyed quite a bit). 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…
Replying to an email? Do the short summary at the top, then write a paragraph or two about the reasons/details/etc - these are also great references.
Encounter an issue and solve it? Write up what it was and what fixed it on a wiki, blog post, even just an email to yourself.
Hacker news? Write comments that are detailed.
Earlier quoted context omitted.
IMO not by much. I mean, it catches out and out errors which is something I guess. And it gives some generally applicable feedback about excessive use of passive voice, overly long sentences, etc. But for the most part it doesn't really improve your writing in terms of structure, clarity, etc.
I always get the feeling that grammarly adds to much commas. And so many of the sentence rewriting suggestions just provide glibberish.
Earlier quoted context omitted.
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
I always like to point at Victor Hugo. In Les Misérables, apparently (I didn't count), more than a quarter of the text is essays which do not move the plot forward. The essay about Waterloo is the most egregious example.
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.
Earlier quoted context omitted.
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
That's not just him, it seems to happen to a lot of authors when they get famous. They get more clout and can push back on the editors, or the editors become afraid to cut too much, and suddenly you have bricks where half the words could be removed.
I took this idea from my PhD supervisor and found it to be incredibly useful. 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 l…