DEVTOOLBOX / GUIDES

Decision guides

How to decide, not just how to click: selection trees, irreversible conversions, and the order to debug when things break. Every guide ends on a tool you can use immediately.

Data formats

JSON: the decision path from validation and formatting to conversion Most JSON work goes wrong at diagnosis, not at the tool. This guide separates four classes of JSON problem, states the evidence each one needs, and marks the points where a fix becomes irreversible: re-serialising, key reordering, number rounding and representation changes. It closes with a debugging order that can be applied to a failing payload without guessing. 11 min read

Encoding

Character encodings and transfer encodings: a decision tree from charset to Base64 Most encoding bugs are layer confusions, not hard problems. This guide separates the character repertoire, the byte encoding and the transfer encoding, then pins down the boundaries you can verify: UTF-8 at one to four bytes, Base64 at four thirds of the payload, JSON escapes under RFC 8259, URL rules under WHATWG. Each section ends with a criterion you can apply and the point past which the damage cannot be undone. 10 min read

Hashing and crypto

Hash, HMAC or encryption: picking the primitive before the algorithm Most cryptographic mistakes are primitive mistakes: a fast hash where a slow one belonged, a keyed hash that can be extended, a mode with no tag. This guide orders the four primitives by what they can prove, gives a criterion and a cost for each choice, and marks the places where a decision stops being reversible. 10 min read

Text processing

Text encoding, Unicode normalization and case mapping: decisions that survive counting, sorting and diffing Text bugs are usually decisions made in the wrong order: a case map applied to undecoded bytes, a comparison between two normalization forms, a truncation inside a grapheme cluster. This guide gives the order to answer in, the criterion for choosing at each step, and the points where a transformation destroys information permanently. Every section ends with something you can check against real code points rather than intuition. 10 min read

Time and dates

Timestamps, time zones, ISO 8601 and week numbers: an ambiguity checklist for time data Almost every time bug is a category mistake: a wall clock stored where an instant was needed, or a zone replaced by the offset it happened to carry on the day the record was written. This guide separates the four things called "the time", then fixes the boundaries you can check: 2^31-1 seconds, 8.64e15 milliseconds, the ISO 8601 and RFC 3339 grammars that overlap without agreeing, and the days that are 82,800 or 90,000 seconds long. Each section ends with a criterion and the point past which data cannot be recovered. 10 min read

Files and documents

PDF workflow order: page operations, content operations and the edits you cannot undo Most PDF damage is ordering damage: text is extracted after a flatten, a watermark is added before a crop, a JPEG is re-encoded once per pass. This guide separates page-level work from content-level work, puts a number on what each pass costs, and marks the three operations that cannot be reversed. Every section ends with a criterion you can apply to the file in front of you. 10 min read

Network

Network troubleshooting order: IP and CIDR, DNS, TCP and UDP ports, WHOIS and RDAP Most network tickets are answered by the layer the symptom belongs to, not by the tool that produced the error. This guide gives the arithmetic behind prefix and host counts, the rules that decide whether a DNS answer or a port state is trustworthy, and the difference between registration data that is redacted and data that is simply old. It ends with a triage order that eliminates local causes before remote ones, and it marks which checks destroy the evidence for the next one. 10 min read

Generators

UUID v4 or v7, password length, QR error correction: choosing a generator by criterion Generated values fail quietly: a token from a weak PRNG still looks random, a truncated password still looks long, a printed QR code still looks scannable. This guide puts the entropy source ahead of the output format, then settles UUID version, password length, QR error-correction level and fixture realism with criteria, costs and the points where a choice stops being reversible. 10 min read

Releases and artifacts

Cutting a release: version numbers, file modes, checksums and compression A release is bytes plus the metadata that tells a stranger how to use them, and most release bugs are metadata bugs: a caret range that admits a breaking minor, an archive that forgot the execute bit, a checksum line published next to the file it guards. This guide orders those decisions, gives a criterion and a cost for each, and marks the four steps that cannot be taken twice. 10 min read