Hacker News Reader

This really struck a chord with me. Writing documentation is an act of explaining something to others. Explaining something to others is a great way to test your own understanding. If it's hard to explain to someone else, then maybe it's the wrong design.

If you don't through that exercise, you're much more likely to build confusing, difficult-to-use APIs.

View on HN

> you're much more likely to build confusing, difficult-to-use APIs.

have not found this to be the case with zig in general. you could easily make the opposite argument, that documenting things (especially quirks) can give you license to build confusing APIs.

I think some documentation and a handful of examples would have helped the author of the article. How is the experience when porting to the new standard library improved by not including documentation?

> > you're much more likely to build confusing, difficult-to-use APIs.

> have not found this to be the case with zig in general.

Dunno how general it is, but TFA we're discussing here contains an example, so AFAICS it seems at least a little too common.

Reply on news.ycombinator.com