On technical writing

  • Written by: Marko Samastur
  • Published on:
  • Category: General development, Catchall

Early this year I was reading a couple of books about Typescript and got really annoyed by basic technical errors and poorly conceived books structures. Python is a strongly typed programming language and if the intended reader is expected to already have mastered Typescript’s basics, then they probably don’t need a chapter on how to install it. I wanted to vent about decline in quality of technical books in recent years, but I am glad now that I didn’t get around writing about it.

This summer I decided to use some of my downtime during treks to update and improve my knowledge of functional programming by reading 3 books on this topic and I could hear my inner voice screaming, again: “Who is this book for?” Too much effort was spent on technical minutiae and none whatsoever on how to actually design and develop programs of non-trivial length, which in my experience is one of the main stumbling blocks for inexperienced developers.

None of these books was new with the oldest coming out in 2012. All three were published by O’Reilly which at least back then was considered a respected source of technical content. So, quality erosion started sooner than I noticed, but still seems to be getting worse with publishers cutting corners everywhere while trying to compete with self-published authors whose books often seem overstuffed with marginally useful information to fatten them to book length, probably to raise their perceived value so they can become a source of passive income and/or improving author’s resume.

Of course some books, self-published or not, are good, but it is becoming increasingly difficult to find them between so many bad ones. Especially since number of online reviewers have not scaled nearly as much and hence most books have few if any reviews.

This is a problem for people like me, who like to learn about a new topic through books, but I think the effects may be larger. Books can be a good way to coalesce and distill knowledge to a package that could serve as a good introduction to topic’s novices. Modern web development has become a complicated affair with surprising and often depressingly short turnaround of technologies used and while it is useful to have someone explain in detail a tool that will likely be largely abandoned in two years time, I find there are not enough of them aiming for longer shelf life by teaching foundational knowledge.

This spring I threw out more than a meter of old, mostly computer-related books that were now completely obsolete and I could certainly do the same with most electronic books that I have, if I could be bothered. While I was doing this, weighing on each book if it still has something valuable to say, a question kept coming up. If I was starting my career today, as many are, how would I even go about it?