10 ms·

I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things thro

by jsty 7y ago

I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things through properly, even if nobody else will ever read what you write. Writing a couple of pages of design docs or an Amazon-style 6 pager or whatever might take a few days of work, but can save weeks or more of wasted implementation time when you realise your system design was flawed or it doesn't address any real user needs.

sokoloff 7y ago
“Writing is nature's way of telling us how lousy our thinking is.” ― Leslie Lamport
- tombert 7y ago
  I love that quote, but Lamport actually says in the Specifying Systems book that he got it from Dick Guindon. I mention this purely in the interest of pedantry.
  - dmreedy 7y ago
    I had a professor who gave me another favorite quote of mine: "It's worth being pedantic at least twice in your life" I think the ideas are related.
- tomfern 7y ago
  I'm stealing that quote, it's so good. I'm always surprised how ideas that sounded wonderful in my head turn into garbage when written down.
  - ithkuil 7y ago
    An actual quote from Lamport: "mathematics is nature's way to show you how lousy your writing is". It's layered on top of a quote of Guindon he uses in a book about TLA+ in order to make a point for using math to formally specify systems
- hliyan 7y ago
  A previous HN discussion on the subject from a decade ago: https://news.ycombinator.com/item?id=993253 https://news.ycombinator.com/item?id=993253 The link has changed: http://www.petermichaud.com/essays/the-secret-about-writing-that-no-one-has-the-balls-to-tell-you http://www.petermichaud.com/essays/the-secret-about-writing-...
Ixiaus 7y ago
And then specify the design doc with TLA+! I agree with your point and I also think English is imprecise. It's great for socializing and flushing out ideas but it can also give one a false sense of confidence.
- Ixiaus 7y ago
  Really there's a general point here I think: up front, careful reasoning (which should eventually excogitation in English or math or code) not only helps prevent mistakes but it also produces documentation and reasoning collateral.
abhishekjha 7y ago
>Writing a couple of pages of design docs or an Amazon-style 6 pager While we are on this topic, how does one design things? I am very new to this and would love some references. Mostly I implement other’s design in code but I have never designed anything myself. I am always fascinated by the idea of writing an RFC like document but even that seems a little too far fetched for me as of now.
- mason55 7y ago
  Start off by writing down a clear goal of what you're trying to accomplish. This is pretty much the first thing I do when I write any document in fact. Then figure out what the requirements are that help you meet your goal and write those down. Once you have a goal and a set of requirements the design is usually pretty easy.
- microcolonel 7y ago
  I think a lot of mature RFCs are based on prototypes. In my experience, prototyping is the first step in design; I know I've seen "designers" and "architects" hide that they prototyped something before writing the document they've been asked to. I know at least one did this to give the impression that they were able to express it fully-formed from whole cloth. Sometimes you can get away with documenting a design based on prior art, but without creating your own prototypes. For the most part, rather than the first, good design documents are the the second or later expression of a design. Added: I think this ties into what jsty is saying. Good designs tend not to be the first iteration of an idea, regardless whether the iterations were intentional design, or refactoring. IIRC, Joe Armstrong (RIP) was a firm believer in the "write it once, then throw it out and rewrite it at least once" pattern of development. I think that whether you're writing a design document or a new version of some portion of code, you are refining a design, and that tends to help.
- allenu 7y ago
  I'm not the poster you're responding to, but for me in my career, I originally tried to design things in more detail up front and write a lot about how it would work. After many years in the industry, I've actually found that it's better to quickly prototype the various "big pieces" of whatever it is you are designing and learn the constraints of the space you are in first. (You're never going to get everything right with that first attempt at a design.) You can write documents up front explaining what you think your code is going to do, but I would actually not recommend going into too much detail because you only really learn about the problem space you are in by doing. In terms of a document, keep the initial design light and explain your assumptions, what the technical constraints you face are and how you plan to mitigate them. This is mostly to share out with other people to see if they have concerns about the approach and if they have ideas to help with the process.
bloopernova 7y ago
I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me. Just adding the following text seems to upset some people: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. It's like they don't want to be pinned down to an exact meaning in design documents! And don't even think about trying to "force" people to use a style guide like RFC 7322, or even an authoritative list of initialisms, acronyms, and abbreviations. Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". This has already gotten too rant-y but it burns my butt so much! So much wasted effort!
- rhapsodic 7y ago
  > Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". I disagree with you, but since I'm shadowbanned, there's no point in explaining why.
- chrisseaton 7y ago
  I don’t think the key to effective writing is following a bunch of standards.
  - MivLives 7y ago
    Standards like grammer?
    - fizwhiz 7y ago
      Not sure if your typo was intentional.
    - jknoepfler 7y ago
      That's a pretty asinine response to a point that is substantially correct. Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time, and will actually reduce the quality of the finished product. No one is here to dispute the usefulness of approximately correct contemporary grammar. I would dispute the usefulness of insisting that design docs conform to APA style requirements or some other nonsense, unless there were very clear reasons for insisting on that level of uniformity (documentation for a pacemaker, for example).
mwfunk 7y ago
This is so true. It's like the old truism about how the way to really truly learn something is to have to explain it to someone else. Literally just going through the process of articulating something, just putting it into words, is an amazing tool for revealing all of the missing pieces and inconsistencies that would otherwise be implicit. Until you put something into words, one way or another, then it's just a fuzzy blob of assumptions and halfway articulated thoughts. The better someone is at writing, the better they're able to articulate their thoughts, even if it's just to themselves.
stcredzero 7y ago
I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things through properly, even if nobody else will ever read what you write. It's the same phenomenon of "rubber duck" software engineering, or when you start composing the very rigorous email asking a question of another programmer, then find you've answered your own question before you complete it. Also, the same general skill for editing text is the same general skill involved in refactoring. You're trying to capture the same semantics, but with a cleaner, more easily digestible structure.
- chii 7y ago
  >> it forces you to reason things through properly the same could be said for using static types to express the thoughts and formal reasoning rather than english though.
  - munmaek 7y ago
    Static types are only one part of reasoning through things properly. Rubber ducking or composing that question to a colleague forces you to think of the entire logic and structure around it, etc. Types won't fix that.
jacquesm 7y ago
As a friend of mine said: "When you write something down you think you are changing the contents of the paper but really it changes you."

by jsty 7y ago

sokoloff 7y ago

“Writing is nature's way of telling us how lousy our thinking is.” ― Leslie Lamport

tombert 7y ago
I love that quote, but Lamport actually says in the Specifying Systems book that he got it from Dick Guindon. I mention this purely in the interest of pedantry.
- dmreedy 7y ago
  I had a professor who gave me another favorite quote of mine: "It's worth being pedantic at least twice in your life" I think the ideas are related.
tomfern 7y ago
I'm stealing that quote, it's so good. I'm always surprised how ideas that sounded wonderful in my head turn into garbage when written down.
- ithkuil 7y ago
  An actual quote from Lamport: "mathematics is nature's way to show you how lousy your writing is". It's layered on top of a quote of Guindon he uses in a book about TLA+ in order to make a point for using math to formally specify systems
hliyan 7y ago
A previous HN discussion on the subject from a decade ago: https://news.ycombinator.com/item?id=993253 https://news.ycombinator.com/item?id=993253 The link has changed: http://www.petermichaud.com/essays/the-secret-about-writing-that-no-one-has-the-balls-to-tell-you http://www.petermichaud.com/essays/the-secret-about-writing-...

Ixiaus 7y ago

And then specify the design doc with TLA+! I agree with your point and I also think English is imprecise. It's great for socializing and flushing out ideas but it can also give one a false sense of confidence.

Ixiaus 7y ago
Really there's a general point here I think: up front, careful reasoning (which should eventually excogitation in English or math or code) not only helps prevent mistakes but it also produces documentation and reasoning collateral.

abhishekjha 7y ago

>Writing a couple of pages of design docs or an Amazon-style 6 pager While we are on this topic, how does one design things? I am very new to this and would love some references. Mostly I implement other’s design in code but I have never designed anything myself. I am always fascinated by the idea of writing an RFC like document but even that seems a little too far fetched for me as of now.

mason55 7y ago
Start off by writing down a clear goal of what you're trying to accomplish. This is pretty much the first thing I do when I write any document in fact. Then figure out what the requirements are that help you meet your goal and write those down. Once you have a goal and a set of requirements the design is usually pretty easy.
microcolonel 7y ago
I think a lot of mature RFCs are based on prototypes. In my experience, prototyping is the first step in design; I know I've seen "designers" and "architects" hide that they prototyped something before writing the document they've been asked to. I know at least one did this to give the impression that they were able to express it fully-formed from whole cloth. Sometimes you can get away with documenting a design based on prior art, but without creating your own prototypes. For the most part, rather than the first, good design documents are the the second or later expression of a design. Added: I think this ties into what jsty is saying. Good designs tend not to be the first iteration of an idea, regardless whether the iterations were intentional design, or refactoring. IIRC, Joe Armstrong (RIP) was a firm believer in the "write it once, then throw it out and rewrite it at least once" pattern of development. I think that whether you're writing a design document or a new version of some portion of code, you are refining a design, and that tends to help.
allenu 7y ago
I'm not the poster you're responding to, but for me in my career, I originally tried to design things in more detail up front and write a lot about how it would work. After many years in the industry, I've actually found that it's better to quickly prototype the various "big pieces" of whatever it is you are designing and learn the constraints of the space you are in first. (You're never going to get everything right with that first attempt at a design.) You can write documents up front explaining what you think your code is going to do, but I would actually not recommend going into too much detail because you only really learn about the problem space you are in by doing. In terms of a document, keep the initial design light and explain your assumptions, what the technical constraints you face are and how you plan to mitigate them. This is mostly to share out with other people to see if they have concerns about the approach and if they have ideas to help with the process.

bloopernova 7y ago

I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me. Just adding the following text seems to upset some people: The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. It's like they don't want to be pinned down to an exact meaning in design documents! And don't even think about trying to "force" people to use a style guide like RFC 7322, or even an authoritative list of initialisms, acronyms, and abbreviations. Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". This has already gotten too rant-y but it burns my butt so much! So much wasted effort!

rhapsodic 7y ago
> Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken". I disagree with you, but since I'm shadowbanned, there's no point in explaining why.
chrisseaton 7y ago
I don’t think the key to effective writing is following a bunch of standards.
- MivLives 7y ago
  Standards like grammer?
  - fizwhiz 7y ago
    Not sure if your typo was intentional.
  - jknoepfler 7y ago
    That's a pretty asinine response to a point that is substantially correct. Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time, and will actually reduce the quality of the finished product. No one is here to dispute the usefulness of approximately correct contemporary grammar. I would dispute the usefulness of insisting that design docs conform to APA style requirements or some other nonsense, unless there were very clear reasons for insisting on that level of uniformity (documentation for a pacemaker, for example).

mwfunk 7y ago

This is so true. It's like the old truism about how the way to really truly learn something is to have to explain it to someone else. Literally just going through the process of articulating something, just putting it into words, is an amazing tool for revealing all of the missing pieces and inconsistencies that would otherwise be implicit. Until you put something into words, one way or another, then it's just a fuzzy blob of assumptions and halfway articulated thoughts. The better someone is at writing, the better they're able to articulate their thoughts, even if it's just to themselves.

stcredzero 7y ago

I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things through properly, even if nobody else will ever read what you write. It's the same phenomenon of "rubber duck" software engineering, or when you start composing the very rigorous email asking a question of another programmer, then find you've answered your own question before you complete it. Also, the same general skill for editing text is the same general skill involved in refactoring. You're trying to capture the same semantics, but with a cleaner, more easily digestible structure.

chii 7y ago
>> it forces you to reason things through properly the same could be said for using static types to express the thoughts and formal reasoning rather than english though.
- munmaek 7y ago
  Static types are only one part of reasoning through things properly. Rubber ducking or composing that question to a colleague forces you to think of the entire logic and structure around it, etc. Types won't fix that.

jacquesm 7y ago

As a friend of mine said: "When you write something down you think you are changing the contents of the paper but really it changes you."