Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I don't care if you write "you" or "u". I do care a lot about clear definitions in technical writing. For example, someone could mention a "system". What exactly does he mean? Is it synonymous to "the servers" he mentions in the next paragraph? Or is there an important difference?

Even worse if people do not even read the text and only look at the diagrams. Hours of meetings could be replaced with minutes of reading.

Even worse if people do not write text at all but only PowerPoint diagrams. What is the meaning of the boxes and arrows? Is it consistent?

Maybe the responsibility should be placed on the readers as well? They should demand better writing.



And units!

Please both put the units in writing and make sure they're correct! Your network does not run at 100 milli-bits per second. A byte (B) is a lot bigger than a bit (b). Mega (M) is not the same as milli (m). Term contract prices are typical per month or per year, so when you tell me the contract is "only $25K", you haven't told me anything. Tell me it's "$25K/yr" or "$25K/mo" and you've told me something.


And acronyms!


I find that the most efficient way to get a point across is to use lists/bullet points in your email.

I have this very smart colleague who writes in long paragraphs and I always zone out somewhere in the middle.

It's a terrible way to figure out the essentials.

I much prefer PowerPoint diagrams that list the essentials over long paragraphs that include the gory details.




Consider applying for YC's Winter 2026 batch! Applications are open till Nov 10

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: