logoalt Hacker News

mikepurvisyesterday at 9:42 PM0 repliesview on HN

This advice makes most sense for tools that have a clear linear flow from beginner to expert. As soon as something is complex enough to have multiple different personas or desired outcomes for the novice user it's considerably harder to structure docs pedagogically.

The extreme case of this is something like Nix, which is notorious for terrible docs, and I think that's in large part because even the basic "install my first package" could involve profiles, environments, flakes, whatever; there's like five ways to do everything and which one you want depends a lot what your "real" eventual goal is.