3 ms·
Documentation. The python example is a bit on the nose. I've not had good times with ROCm's documentation either. Can anyone point to an example of good docume
by JonChesterfield 3y ago
Documentation. The python example is a bit on the nose. I've not had good times with ROCm's documentation either.
Can anyone point to an example of good documentation for a big software system where they can also sketch how that was achieved? E.g. Cuda's docs are pretty good but I've no idea how they came to be, or how they stay up to date. LLVM's docs are a small amount of handwritten webpages which correlate with reality to some extent, the source for which lives in the same repo as the code.
I have an idea that it needs to combine programmers writing some things, some testing infra to notice things like internal links will 404 and some non-developers writing things.
I started trying to document one of my own systems as freeform notes under obsidian and while it kind of works at the time it diverges from reality pretty quickly, and that's without trying to have anyone else working on either the docs or the system.
So what's the proper, established answer to this?
- not_the_fda 3y agoYou have well thought out stable user facing APIs. You can change the underlying implementation but the user facing API remains stable. Then you hire good technical writers to write and maintain the documentation.