4 ms·

> The DocC tooling isn't going to be anymore effective than doxygen or other auto generated documentation without good architectural documentation. A function d

> The DocC tooling isn't going to be anymore effective than doxygen or other auto generated documentation without good architectural documentation. A function definition is nice but knowing you need to decombulate a frobnob before snizzlizing or that decombulation can only safely be done on the main thread is often more important. Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others?

giantrobot 5y ago
Apple's architectural/design intent documentation is sort of hit or miss. The biggest issue (IMHO) with overall architecture documentation is too often it doesn't make it into written documentation. The key insights are sometimes the middle ten minutes of a WWDC keynote or presentation. If you didn't attend that WWDC session or pour over all the recordings you've missed that particular key concept. So you're then sort of feeling your way around some new technology and making it work but it's not as efficient or elegant as if you had the whole picture. Because there's so little documentation time and Apple does not (as a rule) do engineering blogs or similar there's not a lot of of opacity into inner workings or designs. From the outside there's a lot more reading of tea leaves than you see for other platforms.
- codeflo 5y ago
  I see. Engineering blogs do fill some of that role in Microsoft’s stacks. This is not completely ideal either. Blog posts are frozen in time, and newer articles tend to only describe the deltas. So to get a current understanding, you also have to puzzle together various bits and pieces. But at the very least, blogs are easily searchable.
  - giantrobot 5y ago
    While blog posts aren't ideal they're (like you point out) better than nothing. But blogging goes completely against the grain of how Apple operates internally. The WebKit blog is a singular notable exception because that's a highly visible Open Source project. Even the free-form Q&A portions of WWDC sessions are rarely as frank as they should be in terms of usability. No blogs is fine, that's just the corporate culture, but no blogs and no good up to date architectural documentation is a huge problem. It leads to cargo-cult understanding or complete misunderstandings by outside developers. Hell, it leads to cargo-cult understanding by internal developers.
tablespoon 5y ago
> Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others? I also blame dogmatic misunderstandings that have crystalized around "Agile." Maybe back in the day a some cookbook process specified a lot of useless documentation be created, but many people seem to have thrown the baby out with the bathwater and declared all documentation useless or not worth the effort. Also some programming books are to blame. IIRC, the book "Clean Code" completely rejects comments because they can get out of sync with the code and therefore be misleading, and "clean code" should be self-documenting. However, all code can ever tell you is what is, it can never tell you why or what was really intended. Also, when you really think about it, method and variable names are comments too, which can get just as out of sync with what's really going on than a comment block.
- tylerscott 5y ago
  I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.
  - giantrobot 5y ago
    In-line documentation getting out of sync is a purely organizational problem. If documentation is valued by the organization inline documentation won't get out of sync. It's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightforward to fix because it's the same process for fixing an issue in the code itself.
    - aYsY4dDQ2NrcNzA 5y ago
      And presumably you can track down when the inline docs diverged from the implementation, and who did it.

giantrobot 5y ago

Apple's architectural/design intent documentation is sort of hit or miss. The biggest issue (IMHO) with overall architecture documentation is too often it doesn't make it into written documentation. The key insights are sometimes the middle ten minutes of a WWDC keynote or presentation. If you didn't attend that WWDC session or pour over all the recordings you've missed that particular key concept. So you're then sort of feeling your way around some new technology and making it work but it's not as efficient or elegant as if you had the whole picture. Because there's so little documentation time and Apple does not (as a rule) do engineering blogs or similar there's not a lot of of opacity into inner workings or designs. From the outside there's a lot more reading of tea leaves than you see for other platforms.

codeflo 5y ago
I see. Engineering blogs do fill some of that role in Microsoft’s stacks. This is not completely ideal either. Blog posts are frozen in time, and newer articles tend to only describe the deltas. So to get a current understanding, you also have to puzzle together various bits and pieces. But at the very least, blogs are easily searchable.
- giantrobot 5y ago
  While blog posts aren't ideal they're (like you point out) better than nothing. But blogging goes completely against the grain of how Apple operates internally. The WebKit blog is a singular notable exception because that's a highly visible Open Source project. Even the free-form Q&A portions of WWDC sessions are rarely as frank as they should be in terms of usability. No blogs is fine, that's just the corporate culture, but no blogs and no good up to date architectural documentation is a huge problem. It leads to cargo-cult understanding or complete misunderstandings by outside developers. Hell, it leads to cargo-cult understanding by internal developers.

tablespoon 5y ago

> Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others? I also blame dogmatic misunderstandings that have crystalized around "Agile." Maybe back in the day a some cookbook process specified a lot of useless documentation be created, but many people seem to have thrown the baby out with the bathwater and declared all documentation useless or not worth the effort. Also some programming books are to blame. IIRC, the book "Clean Code" completely rejects comments because they can get out of sync with the code and therefore be misleading, and "clean code" should be self-documenting. However, all code can ever tell you is what is, it can never tell you why or what was really intended. Also, when you really think about it, method and variable names are comments too, which can get just as out of sync with what's really going on than a comment block.

tylerscott 5y ago
I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.
- giantrobot 5y ago
  In-line documentation getting out of sync is a purely organizational problem. If documentation is valued by the organization inline documentation won't get out of sync. It's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightforward to fix because it's the same process for fixing an issue in the code itself.
  - aYsY4dDQ2NrcNzA 5y ago
    And presumably you can track down when the inline docs diverged from the implementation, and who did it.