The Grand Unified Theory of Documentation
– David Laing

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.

• Tutorials - Learning oriented
• How-to guides - Problem oriented
• Explanation - Understanding oriented
• Reference - Information oriented

Originally posted at https:/opensource.com/article/19/8/introduction-bpftrace.

bpftrace is a new open source tracer for Linux for analyzing production performance problems and troubleshooting software. It is used by and has had contributions from many companies including Netfilx, Facebook, Red Hat, Shopify, and others. It was created by Alastair Robertson, a talented UK-based developer who has previously won various coding competitions.

Linux already has many performance tools, but these are often counter-based and have limited visibility. For example, iostat(1), or a monitoring agent, may tell you your average disk latency, but not the distribution of this latency. Distributions can reveal multiple modes, or outliers, either of which may be the real cause of your performance problems. bpftrace is suited for this kind of analysis: decomposing metrics into distributions or per-event logs, and creating new metrics for visibility into blind spots.

Git is hard: screwing up is easy, and figuring out how to fix your mistakes is fucking impossible. Git documentation has this chicken and egg problem where you can't search for how to get yourself out of a mess, unless you already know the name of the thing you need to know about in order to fix your problem.

So here are some bad situations I've gotten myself into, and how I eventually got myself out of them in plain english.

Die Moodle-Plattform hat heute morgen um Punkt 8 Uhr alle Rekorde gebrochen. Die meisten Instanzen halten dem Ansturm stand.

Nur ein kleiner Teil der Zugriffe sind im Moment langsam (länger als 5 Sekunden), oder werfen eine Fehlermeldung. Diese konzentrieren sich auf einzelne Server. Einer der Server bekommt DDoS-Angriffe ab und ist deshalb überlastet. Bei weiteren Servern gibt es aktuell Softwareprobleme, die die Performance der Server einschränken. Wir arbeiten im Moment daran, die Probleme einzugrenzen und zu lösen.

Korrektur: die Zugriffe, die derzeit langsam sind, oder Fehler werfen liegen nicht immer bei 1%, sondern schwanken etwas, je nach Last und Situation.

This story begins, as they so often do, when I noticed that my machine was behaving poorly. My Windows 10 work machine has 24 cores (48 hyper-threads) and they were 50% idle. It has 64 GB of RAM and that was less than half used. It has a fast SSD that was mostly idle. And yet, as I moved the mouse around it kept hitching – sometimes locking up for seconds at a time.

So I did what I always do – I grabbed an ETW trace and analyzed it. The result was the discovery of a serious process-destruction performance bug in Windows 10.