Comment by letientai299 | Hacker News Reader

Comment by letientai299 | Hacker News Reader

Parent Full thread

In the software industry, these are several problems that prevent the success of written communication culture:

- Most of the dev are not trained for that. They're trained for finding shortcuts (Google, SO), rushing the deadline and fix the code with any solution they can find. People tend to follow the easy path (fix and forget) rather take time to write good docs (code comment, commit message, wiki, ...)

- Some people have good writing skills, some have good technical skills. The ones who are good at both are rare. So some time the docs are confusing, misleading.

- We're lacking good tooling for writing docs. At my work, people prefer to write on Confluence for its inline-comment feature (before, they write in Google docs). But Confluence (and Google docs), IMO, are terrible editors for technical heavy docs and they can't work offline, don't have desktop, can't be used with external editor (I'm a die hard vim fan). Another example: tools for drawing diagram. The plain text solutions (PlainUML, mermaid) I've tried so far don't work well for big diagrams. The non plain text solutions can't be tracked in git, thus defeat the point of single source trust.

I believe if someone can build a product solve my points on tooling, their product will beat Confluence easily. I don't have any ideas to fix the other 2 points, though.

> Some people have good writing skills, some have good technical skills. The ones who are good at both are rare.

In my experience this is not the case: good programmers are typically good writers. I think it’s due to clarity of organization and of understanding “the problem to be solved”

I would agree, I've worked with scientists and all types of engineers for decades and I think scientists used to rigorous lab work and coders tend to be better writers although it's not a super strong correlation.

I got the opposite experience. People with good technical skills often write dense, skip explaination of topics that they find easy to grasp, assuming the reader also find them easy (which usually is not the case).

I used to do this too - write dense essays and documentation that took forever to read. Then I took a class on business writing at my local university. It was well worth the time. It helped me focus on writing short, terse language that was simple and quick for the reader. If your organization does struggle with producing easy, well written communications I would highly encourage considering they enroll in some sort of 12-week long course with an experienced instructor who can provide direct feedback.

Eh - I find those people are often the same ones who write weirdly dense pythonic one-liners (cause less lines == good), don't write documentation for their code (cause all code they write == self-documenting), and assume that their interpretation of the English language is standard (even though it's often enough not their native language).

> Some people have good writing skills, some have good technical skills. The ones who are good at both are rare.

Anecdotal, but in my limited experience those with poor writing skills are also poor at writing software.

Typically those who have put in the effort to design and understand their solution are also pretty good at communicating their changes.

The people who rush to get things done quickly and have trouble communicating their changes tend to (in my experience) not really understand what they are doing themselves. More often than not in my experience this group of developers mostly implement ad-hoc solutions that eventually have to be fixed up by the "good at communicating" group later.

Reply on news.ycombinator.com