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

221–230 of 385 posts

Re: Undervalued Engineering Skills: Writing Well

#221

Post by jknoepfler »

MivLives wrote: post #208
chrisseaton wrote: post #204

Earlier quoted context omitted.

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

Standards like grammer?

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

Re: Undervalued Engineering Skills: Writing Well

#222

Post by aphextim »

bongobongo wrote: post #106
simonw wrote: post #5

The more experience I get as an engineer, the more time I spend writing documentation, proposals, tutorials and the like. This article is absolutely spot on when it points out that these skills become increasingly important as the size of an engineering organization grows. The biggest challenges in engineering at scale (scale in terms of complexity and size of the team) are around communication. Good writing is how y…

The problem is that many organizations prevent their IT/engineering departments from professionalizing in a way that would allow for this. "We need a month to iterate over requirements and specification" can land like a lead balloon in any project management meeting, because the _non_-engineers don't see any value in it.

When you try to explain to them that implementing a new system they want isn't as simple as installing new kitchen cabinets.

Try to explain that it is like when you install a kitchen cabinet and then open up the door and it leads to an entire new kitchen cabinet set which also needs to be worked on and that cabinet also has it's own kitchen cabinets that need redone as well.

A lot of times (at least where I work) management has a hard time seeing all the layers in the IT systems they use and what appears to them as a simple surface fix/change isn't always the case.

Re: Undervalued Engineering Skills: Writing Well

#223

Post by stcredzero »

jsty wrote: post #4

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

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.

Re: Undervalued Engineering Skills: Writing Well

#224

Post by wool_gather »

samirm wrote: post #160
wool_gather wrote: post #151

Earlier quoted context omitted.

I like this idea on the surface. The flipside though is that if everyone's reading the doc for the first time right before discussion, it doesn't allow for much depth of analysis. Do you also send the materials out beforehand?

I don't see how this would prevent depth of analysis?

Generally people need some time to ponder new input in order to grasp edge cases, work through implications, identify unspoken assumptions, and so on. Some extraverted folks are happy to "think out loud" in a group, but even then it's too easy for a conversation to move quickly past a particular point that deserves more time.

Re: Undervalued Engineering Skills: Writing Well

#225

Post by wool_gather »

Kiro wrote: post #168
wool_gather wrote: post #151

Earlier quoted context omitted.

I like this idea on the surface. The flipside though is that if everyone's reading the doc for the first time right before discussion, it doesn't allow for much depth of analysis. Do you also send the materials out beforehand?

Sending it out beforehand defeats the purpose.

How so? Couldn't you do both?

Re: Undervalued Engineering Skills: Writing Well

#226

Post by starpilot »

JoeAltmaier wrote: post #62

My tech-write wife says the Engineer-writer fault she most often encounters is the 'mystery story'. That's hiding the lead down at the bottom of an argument. Because Engineers like to show their work and don't want to 'give away the ending' until they've proved it right. So put the conclusion right at the top somewhere! Sometime its as simple as putting the last sentence of every paragraph at the beginning of the par…

In college we learned to "spill the beans" in technical writing. Instead of:

> The goal was bla bla... We tried X... That showed Y. We tried Z, which sort of worked. At the end, we modified Z to work, achieving ABC.

should just be

> We achieved ABC toward our bla bla goal using a modified Z. [supporting lines]

Re: Undervalued Engineering Skills: Writing Well

#227

Post by zwkrt »

allenu wrote: post #183
abhishekjha wrote: post #173

Earlier quoted context omitted.

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

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 above. When your PM says they want something in "real time" do they mean like RTOS, seconds delayed, or "twice daily" (since the old system was a monthly batch!)? Is it ok to assume the system is 99% correct instead of 100%? Is it ok if a user sometimes gets a duplicated notification?

These types of requirements and assumptions can affect the complexity of a project 10x if they are not handled properly.

Re: Undervalued Engineering Skills: Writing Well

#228

Post by microtherion »

rgoulter wrote: post #78
JoeAltmaier wrote: post #62

My tech-write wife says the Engineer-writer fault she most often encounters is the 'mystery story'. That's hiding the lead down at the bottom of an argument. Because Engineers like to show their work and don't want to 'give away the ending' until they've proved it right. So put the conclusion right at the top somewhere! Sometime its as simple as putting the last sentence of every paragraph at the beginning of the par…

I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status. This sounds like a good piece of advice to keep in mind. It's nicer for the reader to not have to wait till the end to get what's going on.

> I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status.

I agree, but maybe that style of writing has evolved for good reasons? In engineering, it seems to be a common personality trait that when presented with conclusions first, we tend to formulate reasons contradicting the conclusions, and then dig in on those reasons, to the detriment of trying to follow the explanations that follow.

In the military, on the other hand (which has been cited as an example of "bottom line first" culture in this thread), people seem more inclined to follow orders.

Anecdotally, in my limited time in the military, I had the opportunity of observing both kinds of personalities, and they did NOT mesh gracefully…

Re: Undervalued Engineering Skills: Writing Well

#230

Post by walshemj »

jknoepfler wrote: post #221
MivLives wrote: post #208

Earlier quoted context omitted.

Standards like grammer?

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…

You are assuming that everyone working with the document is a native English speaker and / or has worked to a standards based development system.

Even so back in the day ICL managed to ignore a counter MUST start from Zero in implementing an X.400 stack - and you wonder why the uk No longer has a mainframe supplier.

Post reply on HN