3 ms·

> - the theorist (explanations) Further it's explained that this is where the "understanding" bit comes in. Ugh, so this school of thought is where some of the

> - the theorist (explanations) Further it's explained that this is where the "understanding" bit comes in. Ugh, so this school of thought is where some of the terrible modern documentation comes from... I want the explanations/understanding first COMBINED with a minimal how-to guide serving as illustration for the explanation. Then a quick link to an API reference that INCLUDES snippets of explanations and usage examples (that you'd find in tutorials or how-to guides). Separating thinking about documentation this way leads to horrible documentation where you start with dumbed-down tutorials missing lots of crucial information, and then you have to put in tons of unnecessary effort putting disparate things toget ther in your head. FFS, programmers are rarely students since most of what we learn is learning-on-the-job and never chefs or theoreticians. Tutorials always waste your time so you'd prefer to start with something much denser... only that the only thing denser you easily find are the API docs, and you lack the explanations to understand them and usage exmaples so you have to hunt them for yourself... yuck. As an example of GREAT documentation that combines things well (the API docs contain concise math theory / formular / explanations AND usage examples), take a look at some of the Pytorch docs: https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.html https://pytorch.org/docs/stable/generated/torch.nn.Conv2d.ht...

infogulch 4y ago
I disagree that writings for all these audiences should be dumped into a single disorganized pile. If I'm looking for API docs I don't want to parse through your contrived how-to combined with a shallow tutorial combined with a long treatise on your principles, just give me the damn API docs. Writing with a specific audience in mind is vital to get good results. That said, I'll agree that these should be interlinked. A tutorial that doesn't ever link to practical how to's is terrible, and please include references to theory in your api docs so I can gain a deeper understanding when the design doesn't make sense to me, etc etc. It's easier to write and read when you are assuming the audience of a particular work; you can switch roles when you click on a how-to article, but trying to inhabit all personas at once is exhausting and unproductive.
- catchclose8919 4y ago
  > trying to inhabit all personas at once is exhausting There's no personas, developers don't have three different brains they keep in the fridge and swap the ones in their head with. Just admit that sure, interweaving information to get good quality docs is exhausting. And that we invented this "write for an audience" crap to simplify the work of the writers - "we're lazy or we have limited resources for writing docs, that's why we're doying it this way". It's the same for writers and journalist, the "write for a specific audience" trick is way to lower the effort needed to get reviews / publishers' attention / clicks / views / shares etc. You do it when you're getting started if you ever want to get started I guess. But large scale it produces shallow literature, hard to fact check or contextualize journalism etc. You do it for yourself (the writer) or to save resources for your companies (sure, interwoven/mixed docs are hard to maintain - I'm not even sure how eg. Pytorch's team manages to do that, but probably being the leading ML frameworks attracts top talent from the whole planet to one open-source project so it's doable for them...). But don't sell the bs that you're doing the reader/consumer any service, keept it hones to yourself and others!
- catchclose8919 4y ago
  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.
atoav 4y ago
I agree, the tutorial and the explaination should go in tandem. Start slow and help the users to form the right images in their heads in the beginning.

infogulch 4y ago

I disagree that writings for all these audiences should be dumped into a single disorganized pile. If I'm looking for API docs I don't want to parse through your contrived how-to combined with a shallow tutorial combined with a long treatise on your principles, just give me the damn API docs. Writing with a specific audience in mind is vital to get good results. That said, I'll agree that these should be interlinked. A tutorial that doesn't ever link to practical how to's is terrible, and please include references to theory in your api docs so I can gain a deeper understanding when the design doesn't make sense to me, etc etc. It's easier to write and read when you are assuming the audience of a particular work; you can switch roles when you click on a how-to article, but trying to inhabit all personas at once is exhausting and unproductive.

catchclose8919 4y ago
> trying to inhabit all personas at once is exhausting There's no personas, developers don't have three different brains they keep in the fridge and swap the ones in their head with. Just admit that sure, interweaving information to get good quality docs is exhausting. And that we invented this "write for an audience" crap to simplify the work of the writers - "we're lazy or we have limited resources for writing docs, that's why we're doying it this way". It's the same for writers and journalist, the "write for a specific audience" trick is way to lower the effort needed to get reviews / publishers' attention / clicks / views / shares etc. You do it when you're getting started if you ever want to get started I guess. But large scale it produces shallow literature, hard to fact check or contextualize journalism etc. You do it for yourself (the writer) or to save resources for your companies (sure, interwoven/mixed docs are hard to maintain - I'm not even sure how eg. Pytorch's team manages to do that, but probably being the leading ML frameworks attracts top talent from the whole planet to one open-source project so it's doable for them...). But don't sell the bs that you're doing the reader/consumer any service, keept it hones to yourself and others!
catchclose8919 4y ago
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.

atoav 4y ago

I agree, the tutorial and the explaination should go in tandem. Start slow and help the users to form the right images in their heads in the beginning.