Re:Ask HN: Is there a better way to document complex softwar...
by avip on Sunday November 25, 2018 @01:50PM
(#18528206)
It's pretty straightforward - if it's pdf it's not versioned. If it's not versioned it's a fossil. The only thing I've ever done to reason about a new system is read the tests.
[ Parent
| on HN ]
Re:Ask HN: Is there a better way to document complex softwar...
by artwr on Sunday November 25, 2018 @05:27PM
(#18529476)
Ha-ha, the joke is on you, the systems I have inherited do not have tests.
Joke aside, tests are a great resource when they are present. The other technique I have used was to look at the system like a black box, and only look at the expected behavior at the boundary. Sometimes, it is the fastest way to clear old cruft.
Re:Ask HN: Is there a better way to document complex softwar...
by sjellis on Monday November 26, 2018 @03:06AM
(#18531817)
These days I preach the gospel of the project README: One file, Markdown format, versioned with the code, that says what the project does with high-level concepts, and how to build it and run the tests.
Re:Ask HN: Is there a better way to document complex softwar...
by pvorb on Sunday November 25, 2018 @02:26PM
(#18528446)
I second that. Reading tests is often more efficient than trying to learn about a system through documentation.
Re:Ask HN: Is there a better way to document complex softwar...
by trading_wheels on Sunday November 25, 2018 @04:43PM
(#18529248)
maybe - but the codethat's the hardest to understand (age, size, immature) is often the least tested, or worse the tests have been gamed over time because the previous assumptions are no longer relvevant & the code has changed so much new developers just want them to pass.
related aside - In my experience developers are much more likely to cut out old code than they are to remove or refactor irrelevant tests