Docs

I’m reading How to Open Source by Richard Schneeman (fantastic) and one of his tips is to show documentation code like this (consider documenting ls): ls <desired-path> Rather than the common: ls /your/path/here The idea is that with the latter, someone will copy your/path/here into their terminal, producing an error like this: ls: /your/path/here: No such file or directory This error says: “The directory doesn’t exist.” Which could beget the incorrect question: “How do I create the /your/path/here directory?” ...

Today while reading the Rust Documentation, I encountered a fantastic UX touch. The authors provide this image with each code block that intentionally doesn’t compile: Docs have to show code that’s broken; it’s how you learn. But broken code can also confuse inexperienced programmers. I’ve seen broken code from a tutorial pasted into Stack Overflow with a plea for help, when the solution is in the next paragraph of the tutorial. ...

A missing README is rarely just missing documentation. It usually signals other things, too. A project that’s going to be difficult to set up. When I pull down a project without a README, I’m starting from zero. What kind of app is this? What backend, frontend, persistence layer, and dependencies are involved? Has it ever been set up on my operating system? Answering these becomes homework I didn’t ask for. A project whose purpose may not be clearly defined. What is this project? Why does it matter? Shaky domain language. What kind of users do we have (Customers and Employees, or Players and Coaches)? What can those users do? Without a README, this information is needlessly obscure. What if we have great docs outside the repo? Better than nothing, but docs should live close to the code: a text file in the project. This lets documentation travel with the code, ties changes together via version control, and gives the repo a clear front page. ...

When learning a new language or framework, the first thing I do is read the official documentation cover-to-cover. Choose the latest version, or if you’re stuck with an older version, go with that. For some tools like Go or React, this can be done in an hour or two. For others like Ruby, it’s more of a challenge, so try to focus on the standard library or official guides. Read quickly, try stuff out, jot down a few notes. ...

One of my all-time favorite programming tools is Dash by Kapeli. In this post, I’ll share some tips for leveraging this fantastic program. The ideal audience for this post is someone who uses Dash and wants to use it better. But in case you haven’t tried it yet, let me answer: what is Dash? What’s Dash? Dash is a MacOS application that offers offline access to, and a user interface for searching, hundreds of API documentation sets. ...

Have you ever tried to read the documentation for a Postgres command? Although many consider Postgres’ docs best-in-class, they include conventions that might challenge newbies. In this post, I’ll paraphrase Postgres’ conventions page to help us understand what the documentation for a command is saying. To check the syntax of a command, I start with psql, the REPL, or ‘Read-Evaluate-Print-Loop’, of Postgres. I query using \help , and get output like this for update: ...