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.
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.