4 ms·
Meanwhile programmers are like: Please write documentation! Please. I'm begging you. Even documentation written in Markdown is better than the nothing that all-
by taylodl 7y ago
Meanwhile programmers are like: Please write documentation! Please. I'm begging you. Even documentation written in Markdown is better than the nothing that all-too-often gets created.
A lot of programmers argue the code is the best documentation. No it's not. Source code answers the how and what but it doesn't provide any answer to the most important question of all - why?
Software embodies several architectural and design decisions. What decisions were explicitly made and why were they made? All too often when looking at code I can certainly understand what was done, but it's not at all immediately clear as to why.
On the teams I've been working with I've gotten them to capture these decisions. It's been a great help - sometimes the original implementors can't remember why something was done the way it was done - especially when asked three or more years later.
Admonishing people to write documentation in Markdown would be a nice problem for me to have. Meanwhile I'd just like some documentation at all. Please?!
- ken 7y ago> Source code answers the how and what but it doesn't provide any answer to the most important question of all - why? The vast majority of technical documentation I read doesn't answer why, either. The closest examples I see these days are tech talks (e.g., videos of Rich Hickey talks) and FAQs (e.g., the Python FAQ has a number of "why" questions). Sometimes also source code comments (e.g., the Swift stdlib actually has fairly informative comments). For some reason, even though there is clearly demand for the why, and programmers are happy to supply it, nobody ever wants to provide it inline, in the documentation proper. It's a rare, rare piece of software that doesn't at some point make me tear my hair out and ask "why?!" upon discovering some behavior which is working exactly as documented.
- zimpenfish 7y ago> Source code answers the how and what but it doesn't provide any answer to the most important question of all - why? Currently having this fight - "The code is the best documentation!" has been the answer to my "where is all the documentation?" question. Sure, except there's 2100+ source files spread over 120+ Go packages encompassing 4+ years of development before I arrived. I'll be right back and productive after 2 years of wading through this, ok?