News for hackers. Stuff that matters.
Re:Ask HN: What is the one thing you would change about docu... by countWSS on Sunday September 17, 2023 @04:33AM (#37542818)
More examples, illustrate the range of options and document all special cases. Think from perspective of "what context is this used from?" instead of just listing possibilities. Try to document what is going behind the scenes as much as possible, with minimal local jargon. Making stuff accessible to wider audience for debugging/auditing requires explaining design decisions at high-level(interface) and low-level(what is actually used). Otherwise users will start treating it as black-box binary blobs of mystery "code" that works by magic, because people just don't read source code.

There are no comments on this comment yet.