Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Undervalued Engineering Skills: Writing Well

blog.pragmaticengineer.com

Post reply on HN
Print view View original

261–270 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#261

Post by allenu »

zwkrt wrote: post #227
allenu wrote: post #183

Earlier quoted context omitted.

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…

+1 to prototyping. Having 100 lines of python that does 20% of what you want your full component should do is probably more useful than a 10000 word document outlining 95% of what your component should do. You can lie to yourself in writing but not in code. That being said, documenting in horrendous detail your actual requirements and your assumptions about the state of the world is more useful than either of the abo…

Exactly. Prototyping reveals a lot of engineering constraints that you cannot see just by designing at a high-level. I've been bitten too many times by thinking something is simple because I designed things at a high level (without prototyping) only to find out there are hard constraints as soon as I start writing some lines of code.

I don't know if this is a common technique but I actually like to do a "big bang" type of prototyping where I build out the major pieces all at once to see what the general look and feel of the system is. From there I can make a way more informed decision on what I need to do versus something superficially high level.

For me, the most important thing from early designs is answering the question "what are the unknowns and what are the risks of this project?" and figuring out the right path to remove the unknowns and reduce the risks.

Re: Undervalued Engineering Skills: Writing Well

#262

Post by technofiend »

chrisseaton wrote: post #204
bloopernova wrote: post #184

Earlier quoted context omitted.

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.…

I don’t think the key to effective writing is following a bunch of standards.

>I don’t think the key to effective writing is following a bunch of standards.

Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!

Re: Undervalued Engineering Skills: Writing Well

#263

Post by heisenbit »

In the Middle Age we needed to thumb through huge binders located in a room close to the mainframe. Tedious.

Then we could buy the books. We still needed to thumb through and it took time.

The the wastage of engineering hours was decreased by putting the writing to low level engineers. That was a good idea as it saved money.

That idea could be made even better by having documentation moved to another location by even lower paid staff. Great financial results!

In the meanwhile we got patterns and realized that all software is created the same. Documentation can be recycled and continuous releasing saves time for unneeded reviews.

Software and its documentation is really just assembling blocks. Learning from the leader in that space, Ikea's manuals yielded even greater results. And with additional ingenuity video was introduced. Saves trees, Ikea could learn from us.

These days one does not need to read much anymore, just google a video. And if a problem can't be solved, then agility comes to rescue. Lean development means problems are solved when needed and that is what agile users are for.

Re: Undervalued Engineering Skills: Writing Well

#264

Post by technofiend »

matwood wrote: post #257
jknoepfler wrote: post #221

Earlier quoted context omitted.

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 co…

> Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time I would agree, except the field of programming seems to have a very large number of pedants. Unfortunately, earlier in my career I was in the room many times where the lead or programmers told the PM or stakeholder "well it didn't say that exactly."

>I would agree, except the field of programming seems to have a very large number of pedants.

It's been a few years but at least when I worked as a NASA subcontractor those standards were (IMHO) to both ensure compliance to process and frankly spread around the blame if something failed despite compliance. Since none of us are writing code to fly on the Space Shuttle I'll agree with you most of the time pedantry for the sake of it is a waste of time. Still, if someone wants to be a pedant about writing code for an automated teller machine or a voting machine then I'd say it's time well spent.

Re: Undervalued Engineering Skills: Writing Well

#266

Post by m_fayer »

heisenbit wrote: post #263

In the Middle Age we needed to thumb through huge binders located in a room close to the mainframe. Tedious. Then we could buy the books. We still needed to thumb through and it took time. The the wastage of engineering hours was decreased by putting the writing to low level engineers. That was a good idea as it saved money. That idea could be made even better by having documentation moved to another location by even…

I'm not totally sure what you're doing here, but I like it.

Re: Undervalued Engineering Skills: Writing Well

#268

Post by lpolovets »

ordinaryradical wrote: post #242
lpolovets wrote: post #188

Writing well is an undervalued skill in life, not just in engineering. When you work on a team of peers with similar skills in your field, whether that field is engineering or something else, being able to write well and communicate well become strong differentiators. FWIW, I'm pretty sure that writing (reasonably) well online is what got me a job in venture capital after ten years as an engineer. David Perell (host…

I'm curious about your experience. How do you think your writing translated into value in the eyes of the VC world? Or was it that you'd built a platform online first through your writing and then they solicited you? In my experience my ability here has always been valued after the fact; I have the strong impression that few companies value writing, even as a secondary skill, or see it as a differentiator.

A few positive experiences I've had related to writing:

1) I used to write a lot on Quora. Being an engineer who can write made my future VC partners believe that I could do more than engineering. I'm pretty sure that building a decent readership base on Quora is what put me on my partners' radar in the first place.

2) Writing on my blog/Twitter/etc has helped put my name and my fund's name on more people's radars and generated a lot of leads for potential investments. As an introvert, writing has been an excellent solution to not wanting to go to networking events/dinners/etc. :)

On the startup side, writing/content marketing are great ways to get customers, especially for b2b companies. Having a strong product matters, but being able to articulate the product's value and your company's expertise through writing is incredibly helpful.

Re: Undervalued Engineering Skills: Writing Well

#270

Post by mannykannot »

zwkrt wrote: post #227
allenu wrote: post #183

Earlier quoted context omitted.

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…

+1 to prototyping. Having 100 lines of python that does 20% of what you want your full component should do is probably more useful than a 10000 word document outlining 95% of what your component should do. You can lie to yourself in writing but not in code. That being said, documenting in horrendous detail your actual requirements and your assumptions about the state of the world is more useful than either of the abo…

> You can lie to yourself in writing but not in code.

You can certainly fool yourself in code, and think you have the solution, or part of it, when, in fact, you do not. If this was not the case, prototyping would be meaningless, as you could only write correct solutions.

I would advise abhishekjha to try thinking one or two steps ahead before starting to write the corresponding code, and to pay particular attention to where it does not work out as expected, because without practice, one is unlikely to advance beyond trial-and-error programming.

Post reply on HN