News for hackers. Stuff that matters.
Re:The Opposite of Documentation is Superstition (2020) by pasc1878 on Sunday December 01, 2024 @06:46AM (#42287901)
But it covers only how to use a function if you know what the system is meant to do or know which function to call in the first place.

You need some overalls documentation to explain the concepts and how to put things together. When the user understands that you can use in-code documentation but even then only if you need to use one function at a time - there needs an explanation of how to put things together.

Re:The Opposite of Documentation is Superstition (2020) by ChrisMarshallNY on Sunday December 01, 2024 @07:01AM (#42287983)
That's what I use the README for.

With Apple's docc, you can drop READMEs throughout the system, and they show up in Xcode's doc browser (and can be referenced from the code).

Re:The Opposite of Documentation is Superstition (2020) by eddd-ddde on Sunday December 01, 2024 @02:11PM (#42290041)
Integration tests? They show how the system works as a whole, and they don't go out of date.
Re:The Opposite of Documentation is Superstition (2020) by ChrisMarshallNY on Sunday December 01, 2024 @04:28PM (#42290853)
They are, indeed, useful.

I usually create full-fat test harnesses[0] for my stuff, as that gives a totally realistic implementation example.

But I think having a well-written README is more likely to be useful.

API/implementation documentation (whether docs or tests), are much more likely to be read, than end-user docs.

[0] https://littlegreenviper.com/testing-harness-vs-unit/