https://www.hillelwayne.com/tags/documentation/ Recent content in Documentation on Hillel Wayne Hugo -- gohugo.io en-us Wed, 05 Jul 2023 00:00:00 +0000 https://www.hillelwayne.com/post/problems-with-the-4doc-model/ Wed, 05 Jul 2023 00:00:00 +0000 https://www.hillelwayne.com/post/problems-with-the-4doc-model/ Two universal facts about user documentation: Documentation is really important. We are really bad at writing it. We don’t have good theories on what makes for useful documentation. That is except for the four document model, or Diátaxis.1 I’m glad that people use it. I’m also a little frustrated that people use it even when its inappropriate. My problem is that it’s not a universal or comprehensive model: there’s a lot of documentation people need to write that doesn’t neatly fit the model. https://www.hillelwayne.com/post/alloydocs/ Mon, 13 Apr 2020 00:00:00 +0000 https://www.hillelwayne.com/post/alloydocs/ tl;dr: online Alloy reference here. If you’ve read this blog at all you probably know I’m a big fan of Alloy. It’s a simple, powerful formal method whose entire syntax fits in just two pages. You can learn it in a day and be productive in two. And it can be used to model everything from package management to database migrations to authorization systems. Two years ago I was invited to the Workshop on the Future of Alloy. https://www.hillelwayne.com/post/what-comments/ Tue, 05 Dec 2017 00:40:32 -0600 https://www.hillelwayne.com/post/what-comments/ People say “Comments should explain why, not what.” I feel like starting a flame war today so I’m going to argue that comments should explain ‘what’ too. Please don’t use this as justification to write bad code, okay? Okay. First of all, why shouldn’t comments explain ‘what’? If you need comments to explain what’s going on, it suggests your code is unclear. If I write //weight, radius, price w = 10, r = 9, p = 1 That’s not as clear as saying https://www.hillelwayne.com/post/python-doctests/ Thu, 16 Feb 2017 00:00:00 +0000 https://www.hillelwayne.com/post/python-doctests/ Doctests are one of the most fascinating things in Python. Not necessarily because it’s particularly elegant or useful, but because it’s unique: I haven’t found another language that has a similar kind of feature. Here’s how it works. Imagine I was writing an adder: def add(a,b): return a + b There’s two kinds of ways we can test it. The first is with unit tests, which everybody’s already used to.