undefined

points

[-]

There are certain things that are too obvious to some person at a given time. Hence they would not consider it's worth documenting. Some of those things are important bits and pieces of the theory[1] of the program.

[1] https://pages.cs.wisc.edu/~remzi/Naur.pdf

by iugtmkbdfil8341 hours ago|

prev|

[-]

<< [belief that] knowledge can be replaced with documentation, tools, and processes. [It] cannot. << volume of documentation that I would have to write would be insane

I am not sure those are mutually exclusive. We all know if situations where a person knows of tiny and typically undocumented system quirks. We even have a corporate name for it: institutional knowledge. The issue is that executives think it can ALL somehow be done, when even cursory real life project lift will quickly teach one how insane average gap between documented and undocumented tends to be. Add to that near constant changes to API, versions, systems, people and I can't help but wonder at executives, who really do think this way.

by paganel2 hours ago|

prev|

[-]

It’s way easier (for this type of scenarios) and far more effective to learn by doing than to learn by reading (even tens of thousands of pages of) documentation, that is the crust of it.

by aleph_minus_one1 hours ago|

parent|

[-]

> It’s way easier (for this type of scenarios) and far more effective to learn by doing than to learn by reading

I don't think so: the problem is that there exist lots of parts in the system that are quite complicated but which one very rarely has to touch - except in the rare (but happening) case that something deep in such a part goes wrong a for requirement for this part pops up.

If you "learned by doing" instead of reading, you are suddenly confronted with a very subtle and complicated subsystem.

In other words: there mostly exist two kinds of tasks:

- easy, regular adjustments

- deep changes that require a really good understanding of the system

by jakub_g1 hours ago|

parent|

[-]

I tend to document some tricky non-obvious pieces of knowledge directly above the relevant code. "We have to do X below instead of obvious-first-idea-Y because Z".

Any time a refactoring comes up which moves code around, AI (or my coworkers) remove those comments without thinking twice, and I need to tell them "hey this is still valid".

by flyinglizard1 hours ago|

parent|

prev|

[-]

It's kind of a learning JIT. It's no use to go through and memorize something you don't need in the short term. It's hard to memorize well and by the time you need to draw on the knowledge it's already hazy. This is why you can think of such documentation more as a reference manual and not just plain documentation.

In any case, AI is great for traversing a codebase and producing at least a draft of such documentation.

by chrisweekly1 hours ago|

parent|

prev|

[-]

crust (edge/border) -> crux (heart/essence)