6 ms·

No. Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point

No. Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point of building abstractions, because it's too hard to keep all of the details in your head at one time. Writing code is generally concerned with the low-level details, which are hidden from other parts of the system (and that's a good thing). When you ask someone a coding question, that's what you are testing. To the point of the article, yeah maybe there is some correlation between someone who is good at writing code and good at writing API documentation. The complaint in the article is that the high-level conceptual documentation is lacking. The systems design stuff. The architecture. And while there are certainly people who are good at writing low-level code as well as understanding high-level architecture, that's not always true, as they are very different skillets (and I don't mean this as a slight against anyone, it's probable that most people who are good at one could become good at the other, but in practice, many people's jobs lead them to spend more time on one instead of the other, so that's where they build up skills and experience). Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book (as opposed to API documentation which is more like a dictionary or encyclopedia). You need to be able to pull information together from lots of places, and it must be presented in a methodical way, where (for example) you can't assume that the reader has knowledge of something before you have presented it.

millerm 5y ago
+1 Nicely explained.
rubicon33 5y ago
> Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book Totally agree. When I need to learn a new subject like Core Audio or something I get a book.
- jamil7 5y ago
  A bit off topic but do you have any recommendations for learning Core Audio? Last time I was reading old blog posts and header files to do what I needed.
  - rubicon33 5y ago
    I used this book and I found it to be excellent. https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1 https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_dt_b... It is mainly geared toward MacOS development but there is a section specifically about iOS for things like Audio Session. You will probably still need to keep the Apple docs open for iOS specific stuff here and there but in general the book does a GREAT job of bridging audio theory, with apple's architectural decisions, with low level implementation details. IMO thats the great strength of books, they tie it all together and this one - for me at least - checked all the boxes.
cromka 5y ago
Very eloquently said, couldn’t agree more.
mr_tristan 5y ago
I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentations, and code examples in this type of category. Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and everyone says "cool, it's documented". And then, 6 months later, half the presentation is obsolete, and it ends up being even more confusing because as the reader, you have to investigate what has changed since this presentation happened. I've noticed, if you put some real thought behind maintaining these higher level docs, you don't end up with _tons_ of documentation. And the speed of adoption is rapid. But it takes design, a feedback loop, etc. It's really another kind of deliverable, separate from creating a software product itself.
- cratermoon 5y ago
  > don't even need to be writing per se It's best to have documentation in a variety of communication formats. I cannot learn by watching a video as well as I can by reading, but everyone is different. If the only, or primary, documentation for your product or code is a video, I'm likely to pass on it unless there are no other choices.
- SomeHacker44 5y ago
  Extraordinarily strongly disagree. Documentation should be first, best, and most thorough in written form. It is easily searchable, easily transferred, easily scanned for relevant sections. Do anything else you want for your audienc3, but for me personally if there is not textual documentation, I will consider your system, software, library or whatever effectively undocumented.
  - astrange 5y ago
    You can't rely on documentation to be correct because, like comments, it can't be tested or automatically updated. It's only going to be reliable if the system under it never changes.
  - mr_tristan 5y ago
cratermoon 5y ago
> you don't need to see how your code fits into the whole. GP said a whole, not the whole. A subsystem, abstraction, or whatever, works as a whole, not as unconnected pieces, and the code needs to reflect the organization and concepts within itself as a meaningful whole.
- Dylan16807 5y ago
  > GP said a whole, not the whole. That reinforces the idea that a programmer might be good at one kind but not another.
shadowfiend 5y ago
No. Modern day software strives to do this, but regularly falls short. To craft the abstraction correctly, you need to understand how it is to be used—this is its “whole”. The person writing the internals of the abstraction who does not understand the whole writes the internals poorly. They create a feature that breaks expectations. They optimize a code path whose unoptimized implementation is relied on for one reason or another. The consumer of the code who does not understand the reasoning for these low level implementations starts relying on sub-behaviors that aren’t actually intended. This is why even the low level folks need to understand the (proximate, at least) whole. What you’re describing is the lazy programming strategy that is certainly easier but results in dependency stacks that are brittle. It means you can plug a junior developer in anywhere without a mentor, but it also means QA efforts are enormous or breakage frequent. In UIs, it’s how Apple can rewrite applications in a new framework and lose decades of system behaviors because no one fully understood the whole when they replaced the abstraction. Abstractions are leaky. It is in their nature. Understanding or describing how they are meant to be used makes the leakiness a little more obvious, a little easier to understand. Any given team can choose to be lazy about this of course, and will export the costs to their code’s consumers. The output of a single individual may lack this context, of course. That is why the best abstractions are often created by teams over time: it takes skill in both typing code and devising and describing architecture to create a good tool in the form of an abstraction. It takes those same skills to achieve continuity over time in maintaining a given framework, application, or other abstraction. Documentation is an assist to the tribal knowledge that helps support this continuity, and a way to export that knowledge to new people, and try to make it outlast the original designers if the abstraction.
- adambatkin 5y ago
  Yes, of course, when working on a piece of code (a low-level task), one should know where it sits within the bigger system. One needs to know all kinds of things about what lives both upstream and downstream, as well as some high-level architecture of the system as a whole. But the implication above (which I disagreed with) was that "good coding skills" (and thus a filter during hiring) implied "good documentation skills" does not follow from any of that. Again: Code is always "low-level" (regardless of how much you do or don't know about the rest of the system) just like most API documentation. The complaint of the original article wasn't about API documentation, but about higher-level conceptual documentation being lacking. And just like not all "coders" may be able to design a large and complex system (though they may certainly be able to understand it) they also may be unable to document those high-level conceptual aspects of the system.
deleted 5y ago
[deleted]

millerm 5y ago

+1 Nicely explained.

rubicon33 5y ago

> Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book Totally agree. When I need to learn a new subject like Core Audio or something I get a book.

jamil7 5y ago
A bit off topic but do you have any recommendations for learning Core Audio? Last time I was reading old blog posts and header files to do what I needed.
- rubicon33 5y ago
  I used this book and I found it to be excellent. https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1 https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_dt_b... It is mainly geared toward MacOS development but there is a section specifically about iOS for things like Audio Session. You will probably still need to keep the Apple docs open for iOS specific stuff here and there but in general the book does a GREAT job of bridging audio theory, with apple's architectural decisions, with low level implementation details. IMO thats the great strength of books, they tie it all together and this one - for me at least - checked all the boxes.

cromka 5y ago

Very eloquently said, couldn’t agree more.

mr_tristan 5y ago

I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentations, and code examples in this type of category. Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and everyone says "cool, it's documented". And then, 6 months later, half the presentation is obsolete, and it ends up being even more confusing because as the reader, you have to investigate what has changed since this presentation happened. I've noticed, if you put some real thought behind maintaining these higher level docs, you don't end up with _tons_ of documentation. And the speed of adoption is rapid. But it takes design, a feedback loop, etc. It's really another kind of deliverable, separate from creating a software product itself.

cratermoon 5y ago
> don't even need to be writing per se It's best to have documentation in a variety of communication formats. I cannot learn by watching a video as well as I can by reading, but everyone is different. If the only, or primary, documentation for your product or code is a video, I'm likely to pass on it unless there are no other choices.
SomeHacker44 5y ago
Extraordinarily strongly disagree. Documentation should be first, best, and most thorough in written form. It is easily searchable, easily transferred, easily scanned for relevant sections. Do anything else you want for your audienc3, but for me personally if there is not textual documentation, I will consider your system, software, library or whatever effectively undocumented.
- astrange 5y ago
  You can't rely on documentation to be correct because, like comments, it can't be tested or automatically updated. It's only going to be reliable if the system under it never changes.
- mr_tristan 5y ago

cratermoon 5y ago

> you don't need to see how your code fits into the whole. GP said a whole, not the whole. A subsystem, abstraction, or whatever, works as a whole, not as unconnected pieces, and the code needs to reflect the organization and concepts within itself as a meaningful whole.

Dylan16807 5y ago
> GP said a whole, not the whole. That reinforces the idea that a programmer might be good at one kind but not another.

shadowfiend 5y ago

No. Modern day software strives to do this, but regularly falls short. To craft the abstraction correctly, you need to understand how it is to be used—this is its “whole”. The person writing the internals of the abstraction who does not understand the whole writes the internals poorly. They create a feature that breaks expectations. They optimize a code path whose unoptimized implementation is relied on for one reason or another. The consumer of the code who does not understand the reasoning for these low level implementations starts relying on sub-behaviors that aren’t actually intended. This is why even the low level folks need to understand the (proximate, at least) whole. What you’re describing is the lazy programming strategy that is certainly easier but results in dependency stacks that are brittle. It means you can plug a junior developer in anywhere without a mentor, but it also means QA efforts are enormous or breakage frequent. In UIs, it’s how Apple can rewrite applications in a new framework and lose decades of system behaviors because no one fully understood the whole when they replaced the abstraction. Abstractions are leaky. It is in their nature. Understanding or describing how they are meant to be used makes the leakiness a little more obvious, a little easier to understand. Any given team can choose to be lazy about this of course, and will export the costs to their code’s consumers. The output of a single individual may lack this context, of course. That is why the best abstractions are often created by teams over time: it takes skill in both typing code and devising and describing architecture to create a good tool in the form of an abstraction. It takes those same skills to achieve continuity over time in maintaining a given framework, application, or other abstraction. Documentation is an assist to the tribal knowledge that helps support this continuity, and a way to export that knowledge to new people, and try to make it outlast the original designers if the abstraction.

adambatkin 5y ago
Yes, of course, when working on a piece of code (a low-level task), one should know where it sits within the bigger system. One needs to know all kinds of things about what lives both upstream and downstream, as well as some high-level architecture of the system as a whole. But the implication above (which I disagreed with) was that "good coding skills" (and thus a filter during hiring) implied "good documentation skills" does not follow from any of that. Again: Code is always "low-level" (regardless of how much you do or don't know about the rest of the system) just like most API documentation. The complaint of the original article wasn't about API documentation, but about higher-level conceptual documentation being lacking. And just like not all "coders" may be able to design a large and complex system (though they may certainly be able to understand it) they also may be unable to document those high-level conceptual aspects of the system.

deleted 5y ago

[deleted]