Re:The Documentation Triangle, or, why code isn't self docum...
by catchclose8919 on Wednesday June 22, 2022 @03:17AM
(#31832938)
Also
> a single disorganized pile
Nobody proposes a "single disorganized pile". Sure, it's hard to eg. put bite-sized examples + condesed 'why' explanations into API docs and to maintain such docs, but it's doable - in the ML community some people use notebooks for docs wiriting and sometimes even for development by generating the code from them (sure, this is utterly extremist and I don't like it myself, but it works for some), some kind of renaissance of "literate programming".
I don't say we revive literate programming, but going haf-way between that and "a disorganized pile" is what I meant.
> a single disorganized pile
Nobody proposes a "single disorganized pile". Sure, it's hard to eg. put bite-sized examples + condesed 'why' explanations into API docs and to maintain such docs, but it's doable - in the ML community some people use notebooks for docs wiriting and sometimes even for development by generating the code from them (sure, this is utterly extremist and I don't like it myself, but it works for some), some kind of renaissance of "literate programming".
I don't say we revive literate programming, but going haf-way between that and "a disorganized pile" is what I meant.