https://eclecticlight.co/2021/06/13/last-week-on-my-mac-the-elephant-at-wwdc/ Skip to content [eclecticlight] The Eclectic Light Company Macs, painting, and more Main navigation Menu * Downloads * M1 Macs * Mac Problems * Mac articles * Art * Macs * Painting hoakley June 13, 2021 Macs, Technology Last Week on My Mac: The elephant at WWDC Just as WWDC was about to start, Michael Tsai posted a brief note in which he details how to download and access Apple's old conceptual documentation for macOS, much of which has never been replaced or updated over the last five years or more. By a strange coincidence, this was followed by no less than five videos at WWDC about a new developer documentation system named DocC, which for many commentators seems to have passed unnoticed. Yet both are unmistakable signs of the elephant at WWDC: documentation. Once upon a time, Apple and its Macintosh computers had exemplary documentation in the form of the Inside Macintosh series of printed books, published in collaboration with Addison-Wesley. Those superb volumes were written by technical authors in close collaboration with Apple's engineers, and still grace many bookshelves. By the time that Mac OS X came along, printed books no longer seemed the best platform for Apple's rapidly evolving operating system, and a large series of conceptual guides and manuals were crafted and made freely available. Those are still available if you follow Michael Tsai's instructions, but most haven't been updated for so long that, even when read in conjunction with more recent sources, their usefulness is now limited. Third-party attempts to document Mac OS X have been brave, but none has stood the pace of change. Amit Singh's Mac OS X Internals from 2006 was replaced around 2017 by Jonathan Levin's outstanding trilogy *OS Internals, which was marred only by its lack of an index. But no sooner had Levin completed his series than he abandoned it in favour of documenting Android. DocC looks exciting, and demonstrates that Apple recognises its problem, at least in part. But it falls into several well-known traps. First, it concentrates on documenting calls within an API by individual function. For a developer who already understands how that sub-system in macOS works, that's essential. But trying to grok major topics like Attributed Text simply isn't possible by referring to individual functions within the API. You first need to get your head around how sub-systems are designed and function, the conceptual information which Apple was once so good at providing. Good conceptual documentation is structured and written quite differently from that for classes and functions with an API, as Apple well knows. DocC is the most recent in a long line of schemes to 'automatically' create code and documentation together. The first I can remember coming across was Don Knuth's Literate Programming, from 1984, which is discussed in an excellent article on Wikipedia, which also lists the existing ability to document Swift code using marked-up text, the subject of a fine book by Erica Sadun. No system is 'automatic' of course: there's no getting away from the fact that someone has to write the code, and someone the documentation, no matter how they might be entwined. In common with almost every other initiative of its kind, this approach assumes that the best people to document macOS are its engineers. Those engineers are often selected at interview by posing them a coding challenge, but have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code? Although many of Apple's engineers are - when they're given the time and opportunity - excellent at documenting, many are not. That's not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code. And when it comes to explaining in understandable terms the concepts underlying a sub-system within macOS, I suspect the number of engineers who shine at the task is quite small. In recent years, in the absence of anything better, most developers have come to rely on presentations, their transcripts and supporting materials for WWDC. In some areas, that is essentially the only documentation we have apart from individual accounts of functions in the API. Their coverage is patchy, and important topics may not be covered for several years. For example, there have only been three half-hour sessions covering APFS since its introduction at WWDC in 2016. APFS is another example of the failure of enforced documentation. Compare the fluent accounts of security systems in Apple's Platform Security Guide, one of very few conceptual guides which are maintained to Apple's previous high standards, and those of the enormously complex APFS in its reference, which hasn't been updated or extended for a year. DocC and those previous documentation schemes are overwhelmingly aimed at developers, though, and leave the advanced user to get the gist of the sub-systems which they cover. They omit vast tracts of macOS which aren't intended to be accessed by third-parties, which Apple usually tries to burrow away in private frameworks and closed-source apps. Take Time Machine, for which the only documentation is that aimed at relative novices. It took the likes of the late James Pond (1943-2013) to explore and compile advanced details of Time Machine. This is being harsh on DocC, which is thoroughly commendable, and every developer should watch the five videos devoted to it. But this documentation famine only worsens in Apple, and I really can't see DocC proving a solution. I've had many users report that, when they've taken macOS problems to Apple Support, they've dealt with Apple staff who have even less documentation than do users. Apple's own engineers seem in need too. I gather that the world's biggest customer for third-party books about technical aspects of macOS, including the three volumes of Jonathan Levin's series, is Apple. DocC is in reality a plaintive cry for help. Teams are still trying to fill the yawning chasm: ironically, one of the best new man pages I've read in a long time is that for bputil, a command tool which Apple repeatedly warns shouldn't be used except experimentally. But those are exceptions, and for every instance like that there are tens of man pages which haven't been updated for years and now don't match their usage information. Two failings still trouble Apple and its amazing products: bugs and documentation. Without squaring up to both and changing course, they can only get worse. Share this: * Twitter * Facebook * Reddit * Pinterest * Email * Print * Like this: Like Loading... Related Posted in Macs, Technology and tagged Apple, DocC, documentation, macOS 12, Monterey. Bookmark the permalink. 12Comments Add yours 1. 1 [528d5ed6f32e] Michele Galvagno on June 13, 2021 at 7:52 am Reply It looks similar to what beta testing has become in latest years: lure users/devs to test the upcoming releases with glittering new features, offload responsibility and save the money of dedicated testing teams. I see Swift "pedagogues" rising like mushrooms at the first Autumnal rains, everyone selling their own Eldorado and somehow filling part of the gap in documentation. I really hope that Apple doesn't think bloggers & youtubers are a good substitute for good docs, but seeing the sheer amount of that, they for sure don't feel the pressure. I recall one of the companies were I applied as iOS junior dev 2 years ago, they told me: "All what you studied in Mr X's books & Mr Y's courses is all good, but you lack the basics of the job!" ...which was a deep understanding of how a system worked. LikeLiked by 1 person + 2 [6986a746f627] hoakley on June 13, 2021 at 9:20 am Reply Thank you. Howard. LikeLike 2. 3 [53de3a35b5a8] Francis E on June 13, 2021 at 8:47 am Reply It's a classic piece of yak-shaving. We need better documentation, so let's go down a rabbit-hole developing a new tool for it instead of concentrating on the actual problem. I don't agree with your claim that Apple recognises the problem. They already had and used doxygen. That tool was not the problem. The "Inside Macintosh" of yore was written in Pagemaker. I am writing similar conceptual software docunentation in Apple's own Pages word processor, albeit having to use a program from another vendor for the diagrams, so I know it can be done. All they needed was to put bodies on it - and perhaps fire those of their developers who could not or would not document their design before they started coding, LikeLiked by 1 person + 4 [6986a746f627] hoakley on June 13, 2021 at 9:23 am Reply Thank you. The copies of Inside Macintosh that I have were set using Microsoft Word, as I recall. Apple already uses tools like Scapple for diagramming in the Platform Security Guide. I don't think this is a question of bodies, but employing technical authors, which Apple used to once. I wouldn't fire a single engineer, though: good engineers are worth their weight in gold. Documentation needs the professional skills of technical authors, albeit in close collaboration with the engineers. Howard. LikeLike 3. 5 [IMG_0065_res] rfog y su etiqueta de anis del mono 192.168.1.255 (@rfog42) on June 13, 2021 at 10:00 am Reply Welcome to Wndows, ahem. Microsoft is doing that since about 2001, when they released Visual Studio 2002, with the added "feature" that their system searches but does not find. You must rely in Google search to find what you need into Microsoft MSDN online documentation because their own search engine always return complete nonsense. And after 20 years, they still haven't resolved MSDN search despite the thousands a thousands bug reports filed about that. LikeLiked by 1 person + 6 [6986a746f627] hoakley on June 13, 2021 at 10:09 am Reply Thank you. This isn't about searching. Search can only find what exists. Documentation now either doesn't exist, or was last updated more than 7 years ago and has changed beyond all recognition. Howard LikeLike 4. 7 [60c0a04809a2] EcleX on June 13, 2021 at 10:09 am Reply Developers needing full APFS documentation have been asking for it since June and September 2017, when APFS was announced and release, respectively, for macOS 10.13 High Sierra. They include Alsoft (DiskWarrior), Micromat (TechTool Pro) and Prosoft Engineering (Drive Genius). Is Apple listening? LikeLiked by 1 person + 8 [6986a746f627] hoakley on June 13, 2021 at 10:48 pm Reply Thank you. Howard. LikeLike 5. 9 [1b90d216c330] BKDad on June 13, 2021 at 2:31 pm Reply Really great article - thank you! I suspect this is what inevitably takes place in most companies that are successful and grow well. At first, the focus is on surviving. This requires great products that get people's attention and purchase. Then, as the customer acceptance improves and the company begins to stabilize, the focus is still on the product and the customer, including efficient manufacturing and customer service. That is what keeps customers coming back. The next step is when a company becomes very successful. It then becomes more inwardly focused. Part of that is due to the size of the company and who they listen too. Part is because there's great immediate financial success in optimizing business metrics. Finally, it's because the there are so many forces dominating the company's sightline that making great products and pleasing the customer become just a small part of the mix. In addition, as a company matures, it becomes harder and harder to really make giant product innovations. But, I think the inward focus thing may be the dominant piece with regard to documentation. This sort of thing has happened with lots of companies that were very successful once, and then lost their way in some fashion. Sometimes it's because they think that because they are pretty good at making communications systems that they can also be equally successful at creating artistic media content. (AT&T, to name a recent example.) Sometimes it's because they lost the fundamental reason for their success. Sometimes it's because the company just becomes a cash cow to milk. The list is long. Eventually, this comes back to bite the company in some way. We'll see, I guess. In the meantime, software developers are stuck. End users are stuck, partly because the developers are stuck and partly because they want to be able to properly maintain their systems. LikeLiked by 1 person + 10 [6986a746f627] hoakley on June 13, 2021 at 10:51 pm Reply Thank you. From what I gather, this already bites hard in Apple. We often see elementary coding errors manifest themselves in bugs, glitches which occur because Apple's own engineers often aren't aware of how best to do things in macOS. One of the most persistent is in the dating of updates, which simply doesn't do its date arithmetic correctly. Howard. LikeLike 6. 11 [image-1] Apple and the Elephant in the Room | BTC Tech Group, LLC on June 13, 2021 at 5:47 pm Reply [...] https://eclecticlight.co/2021/06/13/ last-week-on-my-mac-the-elephant-at-wwdc/ [...] LikeLike 7. 12 Michael Tsai - Blog - Old Apple Conceptual Documentation on June 13, 2021 at 8:51 pm Reply [...] Update (2021-06-13): Howard Oakley: [...] LikeLike Leave a Reply Cancel reply Enter your comment here... [ ] Fill in your details below or click an icon to log in: * * * * Gravatar Email (required) (Address never made public) [ ] Name (required) [ ] Website [ ] WordPress.com Logo You are commenting using your WordPress.com account. ( Log Out / Change ) Google photo You are commenting using your Google account. ( Log Out / Change ) Twitter picture You are commenting using your Twitter account. ( Log Out / Change ) Facebook photo You are commenting using your Facebook account. ( Log Out / Change ) Cancel Connecting to %s [ ] Notify me of new comments via email. [ ] Notify me of new posts via email. [Post Comment] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] This site uses Akismet to reduce spam. Learn how your comment data is processed. Quick Links * Downloads * Mac Troubleshooting Summary * M1 Macs * Mac problem-solving * Painting topics * Painting * Long Reads Search Search for: [ ] [Search] Monthly archives * June 2021 (31) * May 2021 (80) * April 2021 (79) * March 2021 (77) * February 2021 (75) * January 2021 (75) * December 2020 (77) * November 2020 (84) * October 2020 (81) * September 2020 (79) * August 2020 (103) * July 2020 (81) * June 2020 (78) * May 2020 (78) * April 2020 (81) * March 2020 (86) * February 2020 (77) * January 2020 (86) * December 2019 (82) * November 2019 (74) * October 2019 (89) * September 2019 (80) * August 2019 (91) * July 2019 (95) * June 2019 (88) * May 2019 (91) * April 2019 (79) * March 2019 (78) * February 2019 (71) * January 2019 (69) * December 2018 (79) * November 2018 (71) * October 2018 (78) * September 2018 (76) * August 2018 (78) * July 2018 (76) * June 2018 (77) * May 2018 (71) * April 2018 (67) * March 2018 (73) * February 2018 (67) * January 2018 (83) * December 2017 (94) * November 2017 (73) * October 2017 (86) * September 2017 (92) * August 2017 (69) * July 2017 (81) * June 2017 (76) * May 2017 (90) * April 2017 (76) * March 2017 (79) * February 2017 (65) * January 2017 (76) * December 2016 (75) * November 2016 (68) * October 2016 (76) * September 2016 (78) * August 2016 (70) * July 2016 (74) * June 2016 (66) * May 2016 (71) * April 2016 (67) * March 2016 (71) * February 2016 (68) * January 2016 (90) * December 2015 (96) * November 2015 (103) * October 2015 (119) * September 2015 (115) * August 2015 (117) * July 2015 (117) * June 2015 (105) * May 2015 (111) * April 2015 (119) * March 2015 (69) * February 2015 (54) * January 2015 (39) Tags Adobe APFS Apple AppleScript Apple silicon App Store backup Big Sur Blake bug bugs Catalina Consolation Console diagnosis Disk Utility Dore El Capitan extended attributes Finder firmware Gatekeeper Gerome HFS+ High Sierra history history of painting iCloud Impressionism iOS landscape LockRattler log logs M1 Mac Mac history macOS macOS 10.12 macOS 10.13 macOS 10.14 macOS 10.15 macOS 11 malware Metamorphoses Mojave Monet Moreau MRT myth narrative naturalism OS X Ovid painting Pissarro Poussin privacy realism riddle Rubens Sargent scripting security Sierra Swift symbolism Time Machine Turner update upgrade vulnerability xattr Xcode XProtect Statistics * 8,938,501 hits Blog at WordPress.com. Footer navigation * About & Contact * Macs * Painting * Language * Tech * Life * General * Downloads * Mac problem-solving * Extended attributes (xattrs) * Painting topics * Hieronymus Bosch * English language * LockRattler: 10.12 Sierra * LockRattler: 10.13 High Sierra * LockRattler: 10.11 El Capitan * Updates: El Capitan * Updates: Sierra, High Sierra, Mojave, Catalina, Big Sur * LockRattler: 10.14 Mojave * SilentKnight, silnite, LockRattler, SystHist & Scrub * DelightEd & Podofyllin * xattred, Metamer, Sandstrip & xattr tools * 32-bitCheck & ArchiChect * T2M2, Ulbow, Consolation and log utilities * Cirrus & Bailiff * Taccy, Signet, Precize, Alifix, UTIutility, Sparsity, alisma * Revisionist & DeepTools * Text Utilities: Nalaprop, Dystextia and others * PDF * Keychains & Permissions * LockRattler: 10.15 Catalina * Updates * Spundle, Cormorant, Stibium, Dintch, Fintch and cintch * Long Reads * LockRattler: 11.0 Big Sur * Mac Troubleshooting Summary * M1 Macs * Mints: a multifunction utility Secondary navigation * Search Post navigation Still Life ++ : paintings of the artist's studio 1 Still Life ++ : paintings of the artist's studio 2 Search for: [ ] [Search] Begin typing your search above and press return to search. Press Esc to cancel. Send to Email Address [ ] Your Name [ ] Your Email Address [ ] [ ] loading [Send Email] Cancel Post was not sent - check your email addresses! Email check failed, please try again Sorry, your blog cannot share posts by email. %d bloggers like this: [b]