4 ms·

I read this a long time ago, and I’m probably not reading it again today, but I remember finding Hillel Wayne’s comment apt—-there really are more dimensions th

• yourapostasy 4y ago
  Thank you for posting that, I totally agree with @hillelogram. My documentation holy grail for large codebases is a codebase that starts with literate programming style programmer documentation, then pinned against tags to that structure is a programmer reference documentation, then pinned against that programmer reference are architecture, devops, and user reference, and cascading onwards to a fully-interlinked structure where the user manual is towards the "leafy edges", and demos/tutorials are all the way at the ending leaves. Smaller codebases can skip with "deep-linking tags" that just jump to say a man page or similar. I basically want a Nix for documentation dependency management. Where if I change how some code behaves, I can see the vast majority of the documentation that change impacts. The doc smell of a chaotically-organized documentation source: when the program version changes, every page in the old version when you try to switch to the new version says it cannot find an equivalent page and offers to jump you to the beginning of the new version documentation. I've heard this called "version aphasia". It is especially frustrating to discover that in the new version there is an exact section with the exact section title, organized in the exact same heading structure. Documentation dependency management is still in the Precambrian era compared to source code, and we aren't doing so hot IMHO there, either.