News for hackers. Stuff that matters.
Re:The Surprising Power of Documentation by barrkel on Monday June 12, 2023 @06:49AM (#36291413)
This is API reference documentation. What you're missing is conceptual documentation and use case examples.

Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect.

Use case examples string together multiple APIs, multiple domain objects, to achieve a high level business objective. When working on a project, you can sometimes get away without this - the existing code can be example enough to copy. You can end up with cargo culting, people copying things without understanding why. But if you have an API for third-party use, which needs documenting, you need to have either a well-seeded set of open source users, or a great set of examples.

Re:The Surprising Power of Documentation by Gwypaas on Monday June 12, 2023 @07:27AM (#36291774)
Rustdoc supports conceptual documentation quite well, including testing the example code. A specialized page is better, but the pareto principle applies.

See the Clap documentation:

https://docs.rs/clap/latest/clap/

Re:The Surprising Power of Documentation by paddy_m on Monday June 12, 2023 @10:03AM (#36293575)
I often call this narrative documentation. It's the antidote to Chesterton's Fence and explains the thinking of the programmer who created the thing. How did that programmer expect people to use their tool.