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

Writing docs well: why should a software engineer care?

surfingcomplexity.blog

Post reply on HN
Print view View original

11–20 of 45 posts

Re: Writing docs well: why should a software engineer care?

#11

Post by verdagon »

The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely:

* Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it.

* Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page.

* Have someone read your first draft. If they ask a question, don't answer it directly! Update your draft instead.

* Use lists religiously! Walls of text tend to repel attention.

My favorite article [0] happened to use all these tips, if anyone wants to see an example. Happy writing!

[0] https://verdagon.dev/blog/higher-raii-7drl

Re: Writing docs well: why should a software engineer care?

#12

Post by cratermoon »

Jensson wrote: post #2

> The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression that you understand something well, but that sense of clarity is often an illusion, and when you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your own…

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler

Re: Writing docs well: why should a software engineer care?

#13

Post by leghifla »

socialismisok wrote: post #7

There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.

Good writing is clearly useful and quite often mentioned. But good reading is very rarely talked about. I think it is even more important.

Too many people cannot maintain attention for more than a few seconds while reading. Or they read "what they want to read" instead of the actual text. Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list.

I tend to write concise documentation, but people always loose some important details that way. So I am now purposefully adding more text than strictly required to be sure important points are really understood.

Like a good teacher repeats at least 3 times the same matter, with a slightly different angle

Re: Writing docs well: why should a software engineer care?

#14

Post by olau »

Jensson wrote: post #2

> The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression that you understand something well, but that sense of clarity is often an illusion, and when you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your own…

I've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation of that API. The former reveals flaws in the machine interface, and the latter reveals flaws in the human interface, so to speak. For instance, you might find yourself spending a lot of text trying to explain the naming and then realize that the naming is simply bad.

Re: Writing docs well: why should a software engineer care?

#15

Post by BlueTemplar »

Jensson wrote: post #10
knighthack wrote: post #9

Earlier quoted context omitted.

> If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. For simple packages, I understand. For anything else, you are committing hyperbolic falsehood if you (or others) claim that it is "easier and faster to just read th…

As I said, well written documentation is impossible unless the codebase is very clean, and trivial to write if the codebase is clean. For anything else the documentation will either be very sloppy with details, span hundreds of pages making it unwieldy compared to browning code where you have tooling to see references etc. I have written and reviewed many design documents and held presentations, I understand the valu…

Well, yes, like for code comments, the most important parts are the whys.

You're also forgetting that in some situations the source code itself might be unreadable to the person : either because it's just not available (including the comments), or because the reader doesn't know the programming languages (with assembly programming being a bit of both).

Re: Writing docs well: why should a software engineer care?

#16

Post by drewcoo »

verdagon wrote: post #11

The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely: * Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it. * Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page. * Have someone read your first draft. If they ask a…

> Use bold text

Really? Why not just . . .

> Shorten

And as an atheist, I can't stress the next one enough. Listicles are not ideacles, or somesuchacle. Lists show a lack of pedagogical thought.

> Use lists religiously!

Re: Writing docs well: why should a software engineer care?

#17

Post by samsquire »

I implement algorithms from descriptions. It's so important that other developers can explain code and be capable of implementing the same thing.

There's usually a critical insight that allows an algorithm to be understandable.

Wikipedia descriptions for btrees, multiversion concurrency control and tries are almost enough to implement them.

I don't like it when developers say the code is the documentation. I don't want to read your code to understand how you implemented the solution to the problem. I would rather read a plain explanation of what you're trying to do and what mental model you used to implement it.

Re: Writing docs well: why should a software engineer care?

#18

Post by Ygg2 »

drewcoo wrote: post #16
verdagon wrote: post #11

The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely: * Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it. * Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page. * Have someone read your first draft. If they ask a…

> Use bold text Really? Why not just . . . > Shorten And as an atheist, I can't stress the next one enough. Listicles are not ideacles, or somesuchacle. Lists show a lack of pedagogical thought. > Use lists religiously!

> Really? Why not just . . .

> > Shorten

By being too terse you risk avoiding some important aspect for documentation, preventing someone from understanding it.

It's a balancing act.

Re: Writing docs well: why should a software engineer care?

#19

Post by jakub_g »

verdagon wrote: post #11

The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely: * Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it. * Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page. * Have someone read your first draft. If they ask a…

About shortening: highly recommend glancing over "On Writing Well" by Zinsser.

If you only have 30s, just look at this page from this book:

https://scholarsandrogues.files.wordpress.com/2015/05/zinsse...

Re: Writing docs well: why should a software engineer care?

#20

Post by MaxBarraclough »

leghifla wrote: post #13
socialismisok wrote: post #7

There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.

Good writing is clearly useful and quite often mentioned. But good reading is very rarely talked about. I think it is even more important. Too many people cannot maintain attention for more than a few seconds while reading. Or they read "what they want to read" instead of the actual text. Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list. I tend to writ…

This reminds me of an old Spolsky blog post on writing specs: [0]

  > Programmers often try to write specs which look like dense academic
  > papers. They think that a "correct" spec needs to be "technically"
  > correct and then they are off the hook.
  >
  > The mistake is that when you write a spec, in addition to being
  > correct, it has to be understandable, which, in programming terms,
  > means that it needs to be written so that the human brain can
  > "compile" it.
[0] https://www.joelonsoftware.com/2000/10/15/painless-functiona...
Post reply on HN