4 ms·

Some general pieces of advice that I think apply to all writing: - Write like you would speak. Think of your writing as an extended conversation with other dev

Some general pieces of advice that I think apply to all writing: - Write like you would speak. Think of your writing as an extended conversation with other developers. - Use the active voice wherever possible. - Strive for clarity and simplicity over overly-complicated industry babble. The smarter you try to sound, the harder you will fail. Of course, there will be some amount of jargon you will rely on, which is fine considering your audience, but even with technical writing the Mark Twain axiom holds: don't use a $5 word where a $0.50 word will do. - The best writing doesn't feel like writing. Take what you've written and read it out loud (to yourself or a friend). Rewrite until there's a natural rhythm and flow to your words. - Don't be afraid of shitty first drafts. Dump out all your ideas without fear of judgment (no one's going to look!). Then go back and re-shape, re-word, cut, etc. I think of it like a sculptor and clay - your first draft is just a gathering of all the clay. The following revisions are about molding and shaping it for your intended audience. - Finally, read good writing. Whether it be well-communicated emails or your favorite SF novel, pay attention to what other good writers are doing and try to emulate that.

V-2 9y ago
> read good writing That's sort of a Catch-22 right there. Can you tell if "your favorite SF novel" represents good writing without having a grasp on what constitutes good writing to begin with? Is writing like cooking (where you don't really need to cook well yourself to be able to tell)?
- robotresearcher 9y ago
  There are plenty of writers who almost everyone agrees are great. For simultaneous clarity and beauty of prose, I like Graham Greene.
- ambivalents 9y ago
  By virtue of it being your favorite, I would think it's doing something right. But glibness aside, you could think about as you read: Is it fully engaging you? Is it communicating a complex idea in a simple and/or novel way? Is it making you feel something? Does it make you want to do something? These are all good markers, because writing is really just about communicating ideas well. And if you don't trust your own judgment, you could look up some of the time-tested classics. Some of my favorites: The Great Gatsby, To Kill A Mockingbird, 1984 (fiction); Warren Buffett/Berkshire Hathaway shareholder letters (business/sales writing).
  - V-2 9y ago
    > By virtue of it being your favorite, I would think it's doing something right That something doesn't have to be the quality of writing as such - eg. I can enjoy a somewhat sloppily written book if the idea behind the plot is captivating and compelling
- jerf 9y ago
  "Can you tell if "your favorite SF novel" represents good writing without having a grasp on what constitutes good writing to begin with?" I think for the purposes at hand, you don't need any expertise in writing to tell whether you want to write short emails with some stuff lifted from a given author. The larger structural aspects of writing a good novel are overlooked by a lot of people, and a lot of people will declare someone a "good author" when every character in their stories are an author stand-in, things appear and disappear for no reason, there is no symbolic or mythic resonance in the story, and every other major structural error that can be made, simply because they like the sentence-by-sentence style of the author or the author has snappy wordplay that they like. That taste is more rare, but also only slightly relevant to the question of whether you can write a 500-word email to the executive team about how important it is to not cut your project.

V-2 9y ago

> read good writing That's sort of a Catch-22 right there. Can you tell if "your favorite SF novel" represents good writing without having a grasp on what constitutes good writing to begin with? Is writing like cooking (where you don't really need to cook well yourself to be able to tell)?

robotresearcher 9y ago
There are plenty of writers who almost everyone agrees are great. For simultaneous clarity and beauty of prose, I like Graham Greene.
ambivalents 9y ago
By virtue of it being your favorite, I would think it's doing something right. But glibness aside, you could think about as you read: Is it fully engaging you? Is it communicating a complex idea in a simple and/or novel way? Is it making you feel something? Does it make you want to do something? These are all good markers, because writing is really just about communicating ideas well. And if you don't trust your own judgment, you could look up some of the time-tested classics. Some of my favorites: The Great Gatsby, To Kill A Mockingbird, 1984 (fiction); Warren Buffett/Berkshire Hathaway shareholder letters (business/sales writing).
- V-2 9y ago
  > By virtue of it being your favorite, I would think it's doing something right That something doesn't have to be the quality of writing as such - eg. I can enjoy a somewhat sloppily written book if the idea behind the plot is captivating and compelling
jerf 9y ago
"Can you tell if "your favorite SF novel" represents good writing without having a grasp on what constitutes good writing to begin with?" I think for the purposes at hand, you don't need any expertise in writing to tell whether you want to write short emails with some stuff lifted from a given author. The larger structural aspects of writing a good novel are overlooked by a lot of people, and a lot of people will declare someone a "good author" when every character in their stories are an author stand-in, things appear and disappear for no reason, there is no symbolic or mythic resonance in the story, and every other major structural error that can be made, simply because they like the sentence-by-sentence style of the author or the author has snappy wordplay that they like. That taste is more rare, but also only slightly relevant to the question of whether you can write a 500-word email to the executive team about how important it is to not cut your project.