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

21–30 of 45 posts

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

#21

Post by TheOtherHobbes »

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it.

One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two.

The getting started project is usually at the hello world level - ok as far it goes, which is not far.

The ref manual typically has a list of all moving parts but often lacks a list of concepts and terminology. So you look up $thing and have no idea how it fits into what you're attempting to do.

A series of mid-level task-based examples ("How do I...") for the most common use cases goes a long way to bridging that gap.

Also list any platform specific quirks. (Not just "To install this use homebrew $name for MacOS and apt-get $name for Ubuntu.")

And run a forum where people ask questions. Collect the most common questions into a literal FAQ and/or include them in examples/reference.

Never say "That's in the manual." Especially not when the manual is 1000 pages long and gives a two sentence description of every feature with no use cases.

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

#22

Post by oxff »

As a software engineer, docs are quite low in priority. You should be using a language that can do documentation, like Rust, Haskell or even TS if you must use JS.

If you are stuck with JavaScript you have to be careful since you might just make an API that is way more permissive than what you intended to do, or similarly if you are writing Java and need to consider what happens when concurrency happens etc.

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

#23

Post by baby »

jakub_g wrote: post #19
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...

Stephen King has a similar few pages in his book On Writing. I really really love the short sentences + short paragraph style. One of the author that excels at that is Bukowski.

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

#24

Post by baby »

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…

I think everyone is capable of reading well-written text or code. The problem comes when it’s not well written, in which case you’re in the real of reverse engineering. And most people are bad at RE.

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

#25

Post by ilyt »

TheOtherHobbes wrote: post #21

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…

I do despise how little there is of examples in most of the docs. Go had a right idea of integrating example code into tests so not only there is one way to add example code, it is also guaranteed to be runnable.

It also have side effect of forcing developer to use their own interface they gave to users so they might notice it is shit before people start to complain (or leave defeated and search for different lib)

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

#26

Post by ilyt »

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…

> Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list.

That's on you. A lot of code use list instead of set purely because set is rarely a basic primitive language offers.

If I see method returning list of users I'm just gonna assume it is unordered, and it usually is unordered.

If you return list that's ordered and that matters for some reason, the docs should say it is ordered and by which key.

If the method is called RunTasks(list) and documentation is "runs a list of tasks" it is perfectly fine to assume it means "runs list of tasks in order" but it is also perfectly fine to assume "runs all of the tasks in parallel".

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

#27

Post by ChrisMarshallNY »

This is something that I've always considered crucial.

However, documentation is a "concrete galosh"[0], so I've learned to reduce the sheer volume of docs, and try to tie them to the code, itself. I write about my approach here[1].

[0] https://littlegreenviper.com/various/concrete-galoshes/

[1] https://littlegreenviper.com/miscellany/leaving-a-legacy/

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

#28

Post by jatins »

A thing that I started doing at previous $work was accompanying projects with an FAQ doc that'd try to answer potential product/support questions. These would be non-technical docs, that grow over time .

And any time I got pinged in Slack I'd try to find the answer in that doc and link to relevant section as response.

While I found that most people would not read through the entire doc when it is written or the first time it is shared for comments (can't blame them, attention spans are rare these days), they did however start referring to the the doc first after a couple of times of getting the doc link in response.

Recently I read a tweet[0] that describe text as a liability, just like code. And now I feel all docs should come with an archival/revival date. We need more "canonical references" and less long living design review docs that are often shared around as reference docs.

[0] https://twitter.com/thesephist/status/1592924904911163392

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

#29

Post by jalino23 »

TheOtherHobbes wrote: post #21

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…

this makes sense I’m guessing this is why I love go and rust so much. it’s like I have the confidence to just figure things out when I get stuck cause of the docs it has

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

#30

Post by zppln »

If you document something well people won't have to nag you over it.

One of my first real job assignments was a relatively large C project (client/server architecture) behind a simple CLI. I was given the opportunity to document it relatively well (not just the CLI, but the internal design as well). Ten years later there are multiple GUI clients implemented, some even at other companies. One guy even replaced the client-server UDP protocol (don't ask) with a TCP one. Aside from reviewing pull requests for stuff like that, I don't think I've ever had to explain how any of it actually work aside from pointing them to the docs.

Post reply on HN