18 ms·
The Elephant at WWDC
- m12k 5y ago> That’s not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code. Strong disagree on that one. Writing good code is all communication - with the computer, with your colleagues, with your future self who doesn't remember how or why you did something. It's written knowledge transfer. Blocks of code, just like paragraphs of documentation, need to both fit into a whole, and be as accessible as possible on their own to someone jumping straight into them (e.g. someone straight from google, someone jumping in to do a quick bugfix or merge fix). The list goes on and on.
- jtdev 5y agoA good coder does not a good technical document writer make.
- bombcar 5y agoThey can coincide in the same person - perhaps Donald Knuth’s form of literate code would be an example - but they’re independent skill sets. And for documentation to truly excel in needs to go far beyond “I transliterated the code into English” or even “here’s all the ways this API can be called” and far into the “here’s how to do what you want and here’s what you didn’t know you wanted.” That last part is often the most missing - documentation that educates and informs on all the new options not just the new ways of doing old things - of which Inside Macintosh is a great example.
- hug 5y agoI don't know why this is downvoted -- it's true. They are two very very different skillsets. I'm an ops guy, not a developer, and willing to hold my hand up and say that I suck at documentation. It's a deficit I recognise and work around: I have often paired up with someone who is better at documentation than I am, but less technically apt or possibly earlier on in their career than I am, because it's easier for me to tie a training piece along with the documentation piece. It's kinda like a win-win. If I didn't do this, generally nothing I did would be well documented. I can write what I think is decent documentation, but I find it tedious and tend to half-ass it. My bad. But that's not even the worst of it. The worst of it is that there are technical document writers in my line of work and the documents that they produce are an order of magnitude more useful and thorough than the best of my documentation. Like you could ask me to spend a week writing a document and them to spend a day and I'd be outclassed. It's a world of difference. I know some guys who are good devs and good technical document writers. I know some who are incredible at one and bad at the other. One human can have two differentiated skills, it's true, but they're not at all intrinsically tied. A good coder does not a good technical document writer make.
- nemetroid 5y agoI haven't downvoted any comment in this thread, but I think the parent post was a low-effort oneliner that didn't touch on the arguments made by the comment it responded to, and as such doesn't meaningfully add the conversation (even if it were correct).
- phlakaton 5y agoYou seem to have the writing chops to be a great documentation writer. What is holding you back?
- rleigh 5y agoI disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer. Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit greatly from. Writing code is only one part of the job, and writing documentation, requirements and design is a big part of the rest, and these parts are just as important. It's often the case that the act of writing down these things identifies inconsistencies and omissions which have not been picked up on during design or code review. And, ultimately, your libraries or application need to be used by other people, and if it isn't properly documented it's going to fall short of expectations since people won't be able to use it as intended.
- Spooky23 5y agoThat’s a fair point, but good technical writing is a skill in of itself. Just like having dedicated UX SMEs on a team improves a product, technical writers do the same, especially for complex systems. It’s not that a software engineer isn’t capable of writing, but more that it’s not their primary responsibility. I also anecdotally believe that having people in roles like this who are accountable for documentation, design, etc improve the overall product as they provide another layer of review.
- valuearb 5y agoGood technical documentation needs dedicated technical writers. Comments and internal docs can be handled by the engineers themselves, but turning that into an organized and properly formatted manual in a consistent style and voice for outside consumption is a specialized task that can’t be done piecemeal by the same people writing the code.
- lanstin 5y agoI sort of think this except I had a job for several years where we had really good technical writers who would sit with various developer and produce far more accessible writing than I ever have. It is valuable for my career to be able to write somewhat well but I am hired and earn my salary in other ways, debugging weird technical things; two days experiments, code reading, and maybe gdb and then one small PR and a short email explaining the issue. Write some nice network server to solve a network issue; implement some feature in a maintainable way. Etc. lot of work and mostly the way of thinking about it is a small piece of that work. The tech writers made a small book that could be handed and/or emailed to people who then integrated with my API with no further interaction between me and them. It was very helpful.
- Benjamin_Dobell 5y agoI believe it depends who the target audience is for the documentation. Writing good documentation requires empathy. Writing good code does also. However, it's in general more difficult to empathise with someone who has a fundamentally different background than yourself. Some developers can write code other developers on their team will easily understand, but they're not necessarily able to understand the way less technically inclined individuals (or individuals with a different expertise) think. Generally speaking, this is why UX is such an important field. Writing good documentation is about understanding the target audience, and being able to understand the user's journey - which may be very different than your own.
- adambatkin 5y agoNo. 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 agoA 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.
- thesuperbigfrog 5y agoApple's issue is that unless the code is open source, the documentation is the only thing available to the "outside of Apple" audience. If the documentation for the "outside of Apple" audience is not good enough without access to the source code, then developers feel it and the overall result is that Apple suffers as a platform.
- TheOtherHobbes 5y agoApple's issue is it doesn't seem to care. I'm going to speculate that improving the developer experience has a low status on the management hierarchy. So even if some people do care they're clearly not being given the resources to do anything about it. And the resources required are tiny. Technical writers are cheaper than developers, and you could hire a top team for $1m a year. Doubling that would still be a rounding error in Apple's revenue stream. Multiplying it by 10 and introducing good management would be enough to make Apple's dev docs world-beating and legendary. Apple could also run developer classes and camps online and f2f, publish its own books, create a regular stream of developer newsletters and tech updates, run forums that are actually useful, and so on. The fact that none of this is happening at scale is... unfortunate. WWDC is a small plug in a big hole, and doesn't come close to meeting the community's needs.
- astrange 5y agoEveryone is pretty expensive when they have to live in Silicon Valley - even if not, anyone who interacts with engineers becomes nearly as expensive due to cost disease. There are other factors preventing improving it, because documenting a new project is effectively adding more people to the project team (even if they're "just" writers) and they still need to learn it by talking to the developers, who might not have the time, so it's not scalable. Third-party documentation scales by not being able to talk to those people and instead reverse engineering everything, but that would lead to embarrassing incorrectness if it was the first-party approach.
- psahgal 5y agoI came to the same realization that Apple doesn't seem to care when I started learning how to build apps on iOS. Coming from Android, I was used to having high level conceptual guides on the core building blocks of the framework. In the Android docs, I found detailed explanations of Activities, Fragments, Views, and other major components. It was relatively easy for me to get started, and the system was designed to be extensible. Google even published blog posts regularly, which I could use to learn more about design decisions. When I made the jump to iOS, though, it was difficult to find parallel documentation for what I was looking for. At the time (this was 2015, mind you), I couldn't find anything beyond API documentation for ViewControllers, Views, Core Data, etc. Most of the major documentation existed on third-party sites like NSHipster. Not to mention code signing. I'm pretty sure I'm one of handful developers at my firm who knows the system well enough to explain how it works...and that was after 2 years of working in iOS full-time. I doubt that Apple will prioritize the developer experience on their platform anytime soon. Edit: In case anyone wants to see the difference... - Google's guide on Activities: https://developer.android.com/guide/components/activities/intro-activities https://developer.android.com/guide/components/activities/in... - Apple's guide on View Controllers: https://developer.apple.com/documentation/uikit/view_controllers https://developer.apple.com/documentation/uikit/view_control...
- xwdv 5y agoDisagree. The difference between professional technical documentation and something a “good coder” whipped up to explain some code is astounding. The skills to write good documentation approach something more resembling an English major than a programmer.
- runlevel1 5y agoI think it's more about being able to see things from the audience's perspective. It's hard to write good documentation without being able to visualize: - What they know - What they don't know - What they're probably trying to accomplish Some of the best API documentation comes in the form of examples, which doesn't draw much on writing skills. That said, explaining high-level concepts/theory does require writing skills, but it also requires the skills described above.
- throw14082020 5y agothis article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples. I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was there such a thing before?.
- duped 5y agoYou could run Doxygen on the header files in /Library/Developer and it would give you something decent that didn't strip the doc comments.
- codys 5y agoThe general apple documentation for functions, etc appears to be pretty much a customized doxygen. One can see this by reading the header files for some of their frameworks and noting the doxygen comments there match up with their web-published documentation exactly. That said: some folks didn't really get the memo, because there are important details that are sometimes included in non-doxygen comments in Apple's headers and thus aren't reproduced into Apple's generated/published docs. In particular, the headers (sometimes) include annotations for specific types included in CF containers for return values.
- JimDabell 5y ago> It also gives developers at Apple a standard tool, was there such a thing before?. Yes, Jazzy, SwiftDoc, and appledoc already do this, plus whatever in-house tool that already existed at Apple before this (they have clearly been using something like this for the past ~15 years).
- throw14082020 5y agoAren't all the ones you mentioned all third party, so I would expect they won't be used at all internally. That makes me wonder if Apple uses open source much internally. Also, DocC is integrated into Xcode, all the others tools could not be.
- leoc 5y agoWasn’t the original Inside Macintosh supposedly a nightmare? Did it improve dramatically over the lifetime of (classic) MacOS?
- bluenose69 5y agoI thought it was very clear, and I kept it on my bookshelf long after it had become irrelevant. I only chucked it to make space for other things on the shelf.
- johndoe0815 5y agoThe original MacOS was vastly more complex than contemporary 8-bit operating systems. I think Apple produced very useful documentation with Inside Macintosh - the Human Interface Guidelines that came a bit later are still useful today. However, I think there was a mismatch of expectations, since the Apple ][ was documented down to the last bit, including the schematics and ROM source code (excluding the Applesoft BASIC developed by Microsoft). The creators of the Mac wanted to force developers to adhere to the abstractions Apple provided with the OS and to discourage developers from using low-level tricks. This enabled Apple to evolve the Mac much further than the Apple ][ series. The last model of the Apple ][ series, the //gs, had to provide a lot of hardware to enable backwards compatibility with software written from 1977 on. In contrast, the Mac survived a relatively pain-free transition to the PowerPC in the '90s, which was one of the first wide-spread uses of binary translation in commercial systems (later used for the transition of OS X to intel and now to Arm) - even significant parts of the kernel were still written in 68k assembler on PPC systems. Of course, there were some significant problems to overcome in the 68k era. One well-known example is that developers (even Apple's developers themselves) abused the most significant 8 bits of addresses to store data. The original 68000 had 32 bit address registers but only a 24 bit external address bus, so the 8 MSBs were ignored by hardware. This was no longer true on the 68020 and later CPUs and caused lots of problems... Talking about the state of documentation of macOS, even the old NeXT documentation was better and more in-depth - though there was no detailed information on the hardware, which causes problems for the developers of the Previous emulator today. Of course, the NeXT systems were much less complex than it is today, even though you already had to cope with coprocessors such as the Motorola 56001 DSP and the i860 on the Dimension color graphics card (which unfortunately could not be programmed directly)...
- johndoe0815 5y agoThe manpage situation was already horrible in early versions of OS X (around 10.2), which gave us lots of trouble getting Ethernet to work on a switch without autonegotiation (ifconfig options listed in the manpage didn't work, since the Xserve G4 driver didn't support it) and OpenLDAP for authenticating Linux clients...
- brandonmenc 5y agoI remember the documentation being pretty good up to and including OS X Tiger - back when Apple was still fighting for marketshare. I haven't tried to write anything for their platforms since then, specifically because the documentation is so poor. I don't have time to track down a bunch of old WWDC videos and hope that they approach something like usable minimum developer documentation when combined. I start that process about once a year and every time throw my hands up in resignation. Life is too short.
- zepto 5y ago> First, it concentrates on documenting calls within an API by individual function. Isn’t this just a misread of what DocC adds? I watched the “Meet DocC documentation in XCode” wwdc session and the very first thing they talked about is how it complies Articles and Tutorials as well as reference documentation and how they can cross reference.
- Grimm1 5y agoI think the reality is regardless of what we want, that at most companies the people who write docs are the people who write code. That doesn't mean it's the best way but it does make it the way we have to deal with a majority of time. That's why building tools to help engineers be better documenters from high level through to the low level is I think in the interest of everyone. In my last company before I jumped, I architected and implemented our full data infrastructure along with one other engineer. Which means I was responsible for high level conceptual documentation and low level documentation all the same and while I've written documentation before and for years I'm not formally trained in it so it was all still basically winging it. Since then I've actually taken a few short courses on writing better technical documentation since I felt it was a weak spot and having tools to assist in making that easier would have been great. Documentation is hard and has been neglected but man does it have major underlying costs to getting it wrong. Everything from on boarding being slow to misunderstandings that cause expensive bugs and everything in between. The root cause is developers have a hard time understanding complex systems and we as an industry are really hit and miss on writing the documentation that would make that understanding easier.
- woutgaze 5y agoCan you recommend a book or course for improving ones ability to write good technical documentation?
- cratermoon 5y agoNot the parent poster but I can recommend some books - The Craft of Scientific Writing, Michael Alley - The Craft of Editing, Michael Alley - A Guide to Writing as an Engineer, David Beer and David McMurrey - On Writing Well, William Zinsser There's also a plethora of stuff on the web, as you might imagine, too much to go into it all, but McMurrey has a website https://www.prismnet.com/~hcexres/textbook/acctoc.html https://www.prismnet.com/~hcexres/textbook/acctoc.html
- spockz 5y agoCan you please share the lessons learned in the courses about writing documentation or perhaps recommend some courses/materials? At my place we have an eternal struggle in “level”. We have some very high over docs, then ADR for specific decisions. At the lowest level we have the api documentation which we find most people don’t read. And then we have some tutorials. Every time I read our documentation it feels very inadequate of conveying all our knowledge and intentions.
- jeffreyrogers 5y agoI've been playing around with Swift/SwiftUI recently and while the documentation is still unclear in some areas, it is significantly better than the documentation for their Objective-C APIs was a few years ago when I was trying to make an iPhone app. Edit: Why is this downvoted? Do people really think the documentation got worse over the past few years?
- ChrisMarshallNY 5y agoI am not a fan of the SwiftUI docs, but I have yet to do a full-fat SwiftUI app. I was introduced to this app, which I think is a great help (I referenced it above): https://swiftui-lab.com/companion/ https://swiftui-lab.com/companion/
- jeffreyrogers 5y agoIt seems like they've improved them quite a bit from what they used to be, but that app is great! Thanks for the recommendation.
- moralestapia 5y agoSomething I really loathe about OS X, and it has been becoming worse with time, is the amount of "processes" or whatever that suddenly take 100% CPU. There's no place to find out what they are. What are they doing, are they from apple or not? You're hopeless, aside from some comments here and there from random members of the community. To this day, I have no idea what 'powerd' is, for instance.
- the-dude 5y agoAnd you couldn't be bothered to do a cursory search? > There's no place to find out what they are. Google worked fine for me. YMMV.
- moralestapia 5y agoCould you please, then, point me to a creditable source regarding what 'powerd' is?
- the-dude 5y agoNo, I couldn't be bothered either.
- deleted 5y ago[deleted]
- wux 5y agoYou can use the 'man' command in Terminal to pull up the man page (see: https://en.wikipedia.org/wiki/Man_page https://en.wikipedia.org/wiki/Man_page) for 'powerd' (that is, by typing 'man powerd'). By doing so, you'll see that it is a "launchd managed daemon" that "manages Energy Preferences."
- tpush 5y ago> To this day, I have no idea what 'powerd' is, for instance. You're in luck, there's an extremely helpful and well written man page on exactly that subject. I will quote in its entirety: "NAME powerd -- Daemon that manages Energy Preferences. SYNOPSIS powerd is a launchd managed daemon. DESCRIPTION powerd is a launchd managed daemon."
- bluenose69 5y agoI just watched https://developer.apple.com/videos/play/wwdc2021/10166/ https://developer.apple.com/videos/play/wwdc2021/10166/ to learn about docC, and it looks pretty much like what folks have been doing in other languages for a long time. For example R developers usually document functions, data, etc using Roxygen in-line comments and they use vignettes for tutorials and the like. An additional advantage of R is that it checks that the documented function arguments line up with the code function arguments (at least by name -- it has no way to judge whether what the developer makes sense, of course). I'm not saying that this is not useful, because I think it is, very, useful. It's just that this seem more like catching up than leading, at least in the broad strokes.
- JimDabell 5y ago> it looks pretty much like what folks have been doing in other languages for a long time. It looks pretty much like what folks have been doing in Swift for a very long time. DocC is just Apple’s own version of Jazzy / SwiftDoc / appledoc. There’s no catchup here, it’s just Apple making an “official” version of something that already exists.
- astrange 5y agoApple's comment system has existed for much longer than Swift. https://en.wikipedia.org/wiki/HeaderDoc https://en.wikipedia.org/wiki/HeaderDoc
- jurip 5y agoAlso: Xcode has been able to parse and display the Markdown documentation comments in Swift code for years. It's really nice! Doesn't mean DocC isn't worthwhile, but at least the PSOTU and Meet DocC presentation seemed to not only ignore outside prior art, but Xcode's existing capabilities too.
- bob1029 5y agoConversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-collection/ https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have developed a very strong understanding for how GC works in .NET and how I should strategically approach it for certain types of problems. I would also have clear, specific code examples to follow as appropriate. The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements. Good luck doing something even remotely like this with Apple.
- traspler 5y agoWhen I had the opportunity to do something with a Hololens (1st Gen) I was a bit hesitant as the subject matter seemed very difficult and I come from a very different background but when I went through the documentation, tutorials and played around with the SDK I was shocked how simple the SDK and how clear the documentation was. Haven't worked with much MS things besides that but it left a very good impression.
- phamilton 5y agoAzure Cloud Patterns is an amazing set of system design documentation. It's not even about Azure, it's just "here's how to design good systems".
- reasonabl_human 5y agoOne of my favorite bundles of docs to peruse through from time to time. I go in with a specific question and end up going down the rabbit hole of learning a ton of other interesting design patterns instead
- defaultname 5y agoMicrosoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Apple seems to have decided that people really want a tiny subset of members to have primary documentation, and then a weird collection of orthogonal things mixed in as equal interest so you can't tell what you're looking at. It really is quite terrible.
- hamiltont 5y agoPassion comment: I'll second that most of Jonathan Levin’s books are outstanding, some of my favorite technical guides. Spent many years as senior dev for a custom Android ROM, yet Levin's book still introduced me to multiple other Android internals I had not yet looked into. Would happily pay 200-300 for his next Android book. Probably not the best books for a total beginner, but if you're already skilled and looking for the next level I would highly recommend. My only real complaint is that JL seems to do a lot of the marketing/date-setting himself, and it shows. It can be really confusing to keep current on what book he is working on next, what topics will/will not be covered, how to even pay for the book can be a bit complicated (send paypal to this email), etc. It is fantastic that he adjusts and expands book contents as the market/technology changes (e.g. always chasing to get the newest stuff covered in the newest book), but the current end result is a stream of "update" messages on his website that are hard to follow. Would be wonderful if he had someone help him with that "public-facing" side and try to keep things organized/consistent/obvious and hide a bit of "how the sausage is made"
- auggierose 5y agoJust tried to order the Levin books macOS/iOS books (wasn't even aware of them), but they don't ship to the UK ... Must be security restricted ...
- hamiltont 5y agoWOuld not be surprised - he's reported piracy issues in past. FYI I've ordered all books by emailing directly to an email on the website. He replies with "send paypal to xx if you want digital only, send xxx if you want me to mail you a hardcopy". clunky relative to an amazon order but it gets the job done
- auggierose 5y agoOh, very cool, didn't know that digital only was an option!
- mooreds 5y agoI have loved documentation for a long long time[0]. In my mind, as the developer continues to drive technology decisions[1], documentation in all its forms will continue to be a differentiator on par with functionality. Developers are learning all the time because their job is changing regularly, and good/excellent documentation is a competitive advantage. w/r/t the article, I feel like engineers should write documentation, but so should product managers and customer service reps. I feel like both explicit (written by principals) and emergent documentation (forums) make sense. It's an admittedly big lift, but if no one can figure out how to use your library/package/software, in the long run you'll be beat by folks who make it easier to do so. 0: https://www.mooreds.com/wordpress/archives/6 https://www.mooreds.com/wordpress/archives/6 1: https://www.oreilly.com/library/view/the-new-kingmakers/9781449368036/ https://www.oreilly.com/library/view/the-new-kingmakers/9781...
- mooreds 5y agoIncidentally, if you are looking for a mental model around tech documentation, I haven't found a better one than this: https://diataxis.fr/ https://diataxis.fr/ which discusses tutorials, how-to guides, technical reference and explanation.
- lanstin 5y agoI always thought part of the reason node took off so quickly is that the intro docs all had a five line complete code example that was an http server. And when I wrote APIs for customers, I felt I could not do a good job in the API design unless I write an example that used the API, and then I had good sample code to share. I find all three things: conceptual framework “how to think about this API”, example code (with important error handling paths, just just postman collection), and thorough documentation on all the technical details are all important. Tho obviously the latter is done automatically now usually. But it is important to get out things like “I will return 429s and your code must have a good exponential back off/retry policies” to developers at the beginning.
- jeremymcanally 5y agoThis post (while not wrong that the docs lack in a lot of areas) is written with apparent ignorance of how documentation is generated and published at Apple. Right now creating the code and docs are mostly decoupled. Having worked in the department where the docs are made, a tool like DocC is going to let the engineers who work on the code provide better docs to the Devpubs department so the authors there can stop writing things engineers should be writing (since they know it better) and get back to writing the higher level conceptual stuff that requires skill with technical communication that engineers may lack. They’re a small but mighty team that’s constantly overwhelmed, so I look forward to seeing how DocC can help them out and produce more docs.
- cratermoon 5y agoIf giving Apple developers tools that automatically generate useful API reference documents frees up the devpubs team to generate the other kinds of documents necessary, I'm all for it. If there's nothing but the API documents, DocC won't really address the issues. > They’re a small but mighty team that’s constantly overwhelmed Perhaps Apple needs to spend some money and effort there, but that sounds like a management problem.
- BossingAround 5y ago> They’re a small but mighty team that’s constantly overwhelmed I think this is an incredibly common situation. Personally speaking, I find that to be an excuse. If a woefully understaffed team of tech writers got the budget for 15 new tech writers, that usually wouldn't solve the problem. The main issue is developers who don't believe documentation is highly important. The "we generate documentation, so we're covered" is exactly the attitude I'd describe as highly unproductive. Of course that's great, but auto-generated docs are a small part of what should be your overall documentation suite. It shouldn't become the developers' excuse for not spending more time on documentation. Tech writers will very rarely write docs from zero. I wouldn't even be surprised if the tech writers at Apple had no access to the source code, in which case they can't possibly write the docs from zero.
- Apocryphon 5y agoMany teams at Apple are small but mighty and constantly overwhelmed. It speaks to the priorities of management to engender the existence of these situations. Or the sclerosis of the company culture.
- ChrisMarshallNY 5y agoDISCLAIMER: I used to own the entire Inside Macintosh series (when it was only two or three books), so I know how far the great have fallen. > 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. It's pretty par for the course, for generated documentation (headerdoc kind of thing). Much of my own documentation is done the same way. I agree. It isn't actually that good for systemic understanding (I use big fat READMEs for that). However, you can do things like use MARK commands and extension blocks to organize the docs. Jazzy, in particular, is good for this. The new Apple doc generator will probably also be good for it. But Apple's documentation has definitely gone into the skip, and I am glad to see it being addressed. It has reached the level of brand damage; which is usually where they start paying attention. That said, I completely understand the challenges of keeping documentation current. If we aren't careful, documentation can become a concrete galosh[0]. [0] https://littlegreenviper.com/miscellany/concrete-galoshes/ https://littlegreenviper.com/miscellany/concrete-galoshes/ > 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? I once took an iOS class with a woman who wrote a lot of the graphics subsystem documentation for Apple. She was damn impressive (had a Ph.D, but wasn't actually an engineer -she was a writer). Apple hires good people. Unfortunately, I suspect that she may well have retired, by now. I wrote this comment[1] as a story about an Apple interview that I did, several years ago. It was quite disappointing to encounter their attitude. [1] https://news.ycombinator.com/item?id=21377358 https://news.ycombinator.com/item?id=21377358 I've written about my own experience and practice, in regards to documentation[2]. [2] https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/
- traspler 5y agoThe way Apple talks about new developer features/systems seem like ads for very exclusive clubs sometimes. "If you are already doing this, you can do it here now and we show you some teases, talk to us if you want to know more". One example for me is ReplayKit... yes I don't know too much about Audio/Video but the little documentation there is it feels deliberately obfuscated and lacking. Better API level docs would help but it absolutely needs more high level guides and examples. One WWDC talk linked on a page is not enough.
- valuearb 5y agoNew Kits are always tacked on, there are few overviews to tell you how an entire area works. I once spent days trying to update old AV player code get close captions working with Vimeo streams on iOS, half that time was just trying to understand how captions worked in AV streams at all. Every time something like AV gets a new set of APIs, Apple should update a detailed overview that explains we used to do things this way, then added these Kits to make it easier to do these things and you should only use them for these specific things now, because we have now have added these new Kits to address these new needs, or make this other thing easier, etc. And I’m sick of watch videos. Give me a high level overview of the why and how of the managers, and in it link directly to detailed documentation pages, sample source code and pertinent WWDC videos so I don’t have to use my Google fu to figure out those links myself.
- smoldesu 5y ago> And I’m sick of watch videos. Give me a high level overview of the why and how of the managers, and in it link directly to detailed documentation pages, sample source code and pertinent WWDC videos so I don’t have to use my Google fu to figure out those links myself. This is what I'm personally tired of. WWDC might actually be interesting if they focused on the developer...
- traspler 5y agoWhat I've witnessed a couple of times is that there can be tremendous amounts and great documentation if the feature/framework can be broadly marketed. If it's on a marketing pamphlet it gets a lot of attention but as soon as it becomes standard or a bit less desirable the quality and extent of the docs are the first thing to go it seems. Sometimes "better docs" is the marketed feature but as all marketing campaigns go, they seldom leave a lasting impact.
- dorkmind 5y agoI've actually wondered if a True Hipster (tm) ever thought of starting a company to develop software for vintage Apple hardware emulated by one of the many open source choices available. The thinking here is that such software affords a higher degree of reliability since the platform is totally dead. The thinking for a long time was that computer software was compute-limited, that all applications were as intensive as video games, audio / video editing, and 3D rendering. In reality, people may pay for innovative interfaces and data formats when they organize their work in a new way. Software could be used in an "offensive" way to take entire industries as interlocking roles within organizations. Each of these roles, save manual labor and janitorial work, benefits from education, and the nature of that education is to develop certain patterns of thought & behavior. Software could be designed with the educational background of the user in mind. I'm speaking mostly of enterprise software here, but it could be applied to CAD shops, publishing, anyone who has an education and uses a computer. I'm not talking about Mechanical Turk here. The idea is to take education philosophy as the common software for all education computer-enhanced roles and design software for educated people that exposes stuff like - the ideal way to learn the structure of the software data model - text and point-and-click data input and output - data processing language
- ChrisMarshallNY 5y agoI do want to give a shout-out to this tool[0]. The "official" SwifUI docs leave something to be desired, so a developer wrote an awesome doc tool. I found out about this tool from an instructor at a class I took. [0] https://swiftui-lab.com/companion/ https://swiftui-lab.com/companion/
- Grustaf 5y agoThe official SwiftUI tutorials are absolutely amazing though. But I agree about SwiftUI-labs and the app, they are fantastic resources if you want to go deeper.
- djoldman 5y agoGenerally you find good or great documentation where selling the product depends on it. Apple is a hardware company, despite the money made from the app store. They don't lack for outside developers fighting bad documentation to make apps. Poor documentation is not surprising at all; it's to be expected as there is little incentive to change.
- cratermoon 5y agoWhat's happening here is that Apple is only producing, weakly, reference materials. There need to be at least three other kinds of documentation. The one the author focuses on that's missing is the explanatory type. The sort that's discursive and provides a broader understanding of the whys and hows of the code. Two other kinds of useful documentation that would complete the package are tutorials, of the sort aimed at programmers just starting out with the material, and how-to-guides, for programmers that have a general understanding of the material but could use examples and steps to accomplish a specific goal with the system.
- the_arun 5y agoDoes `docc` works only for Swift? Could we use it for other programming languages? eg. Java
- josephcsible 5y agoBasically every other programming language has already had something like this for a long time, e.g., Javadoc and Doxygen. Is there a particular reason you'd rather use DocC than these well-established alternatives?
- the_arun 5y agoJavadoc seems very restrictive in terms of user interface, search etc., It is also not interactive. Hence, looking for something better.
- jurip 5y agoI'd love to use it for Objective-C too. I work on a mixed language SDK and right now use Jazzy which is fine but I think there's a realistic chance DocC will lead to Jazzy being abandoned sooner than we can get rid of all the Objective-C.
- luckyorlame 5y agoWriting code and writing documentation are completely linked, if you can’t do one, you probably can’t do the other.
- merrywhether 5y agoIsn’t this a little like saying that because I can’t express myself well in Finnish, I probably can’t express myself well in English? Or maybe more like saying that writing about a topic and speaking about it are completely linked? There’s a difference between having/understanding an idea and being able to express it in different modes/mediums of communication (in this case, to computers vs to humans). I’m not saying that one can’t learn to be better at a form of communication, but I recognize they are different abilities.
- hermanradtke 5y agoOne of the people who presented DocC used to lead both the rustdoc and docs.rs teams. You can see Ferris, the Rust mascot, on their desk. I think quality documentation can be written within the markdown that explains how higher levels concepts work. I see this in Rust all the time.
- cratermoon 5y agoOff topic: I didn't know the Rust mascot was named Ferris. That's a lovely play on words.
- kccqzy 5y agoI thought Ferris was named after ferrous oxide, which is the old name for Fe(II) oxide. But chemically, rust consists of Fe(III) oxide, or ferric oxide. So perhaps a more appropriate name would be Ferrick?
- cratermoon 5y agoA little artistic license is better than foolish pedantry.
- kace91 5y ago>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? This was part of the code challenge at the company I'm currently working for. Checking how the candidate's solution was documented is a well defined part of the review process.
- afavour 5y agoThis speaks to me. I’m not deeply involved in the iOS development world but I do a lot of webview-adjacent stuff so I keep a close eye on the WKWebView documentation. It’s a mess. Case in point: introduced in the new beta: loadSimulatedRequest: https://developer.apple.com/documentation/webkit/wkwebview/3763094-loadsimulatedrequest?changes=latest_minor https://developer.apple.com/documentation/webkit/wkwebview/3... What does it do? Don’t know. I can make a few informed guesses from the name but I’m not sure if it’s maybe a performance measurement tool, or just a way of loading faked data. There is no documentation. To the best of my knowledge it isn’t covered in any talks either.
- Fordec 5y agoWow, I think that's my new go to example for bad documentation. That may actually be worse than no documentation because you wasted time looking for what is in essence a mere repeating of the function call and nothing else.
- threeseed 5y agoNot sure why. It's nothing more than an autogenerated documentation page for a method that hasn't yet been documented. And it's specifically listed as being recently added so that explains why. I find pages like this all the time in the Java, Rust, Python etc ecosystems. At least with Objective-C/Swift the method signatures are consistently well named.
- tayistay 5y agoSometimes you have to look in the headers. I don't know why it doesn't get parsed into the docs. Here's the documentation for loadSimulatedRequest: /*! @abstract Sets the webpage contents from the passed data as if it was the response to the supplied request. The request is never actually sent to the supplied URL, though loads of resources defined in the NSData object would be performed. @param request The request specifying the base URL and other loading details to be used while interpreting the supplied data object. @param response A response that is used to interpret the supplied data object. @param data The data to use as the contents of the webpage. @result A new navigation. */
- stephencanon 5y ago> have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code? FWIW, when I’m involved in hiring, I absolutely consider this a major factor.
- cratermoon 5y agoThere's usually a vague "communication skills" aspect of interviewing, but it's not formalized. I'd be interested in hearing how you evaluate candidates for this.
- stephencanon 5y agoPart of my team’s interview process is a small do-it-at-your-leisure at-home exercise in a repo we provide. Beyond the “solution”, we also get to see tests, documentation comments, commit messages, etc.
- deleted 5y ago[deleted]
- giantrobot 5y agoFrom my perspective, I was in SWE at Apple for over a decade, their documentation started going downhill as iOS development ramped up. By the time they got to the yearly release cycle for macOS and iOS documentation was an afterthought. Most was generated with doxygen from inline docstrings. The reason I think the quality and quantity dropped was the internal schedules barely (or don't) leave enough time for the engineering work so there's very little time available for high level documentation. Internally tons of "documentation" existed as Radar comments or exchanges on internal mailing lists. Maybe a group's wiki had some crystallized documentation or high level architectural descriptions but good luck accessing it from outside that org. My favorite was some discussion about overall design or architecture that got the "let's take this offline" where all the helpful details ended up shared in an in-person meeting. The internal secrecy and rapid development pace made it really difficult to get good overviews of technologies internally. I really sympathize with outside developers trying to cobble together an understanding of something where the documentation sucks or is missing. 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. I can read a function signature but I can't necessarily know all the keys that go into some configuration NSDict passed into it. I hope the situation improves if the DocC tooling lowers the friction for writing documentation. It sucks having to mix a WWDC presentation, sample code, and iffy docs into a semblance of usable architectural documentation.
- codeflo 5y ago> 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?
- worik 5y agoI learnt to programme on a Mac Plus using Pascal (Lightspeed? I cannot remember the brand). Inside Macintosh is still, after thirty years, in a box some place. I will never throw it out. Well thumbed, and very useful. Been nearly a year back with Apple hardware now. What a change! The tools are very flash, but nothing quite works. The easy bits are done, feels like 95% of perfect. The documentation is good if you just need to be reminded, but if you need anything to help in the early part of the learning curve, it is third party blogs, (that really feel to me like astro turf, but they do exist). The licensing! Why do I keep getting blocked from using hardware bought and paid for! My colleagues and I have spent, literally, days trying to get me into some sort of licensing scheme - truly Kafkaesque. It feels a lot like Linux in 1997 - mostly works and brimming with potential. But whilst Linux was on its way up in 1997, Apple feels like it is on its way down. And they are busy fighting to keep quasi legal monopolies instead of fixing the last few problems in their tools and writing proper documentation. What a shame
- 3grdlurker 5y agoIt’s odd that no one has pointed out yet that the article is conflating macOS user documentation with developer documentation. In the first place, and this is an unpopular opinion, people have simply accepted “Apple's documentation sucks” as truth but the documentation problem hasn’t been properly defined or framed yet. I personally think that the view, view controller, Core Data, animation, networking, and Bluetooth, and concurrency guides are excellent. What parts of the Apple SDKs exactly are people having a problem with? If it’s just the latest APIs like SwiftUI, does that make the whole platform deserving of an unqualified negative perception? I don’t think so, and it doesn’t help that in my experience, the people who complain the most about Apple’s documentation are the ones who go to a Medium article first and before consulting Apple’s own documentation.
- andrekandre 5y agomy interpretation of this situation is, if (whether by intention or not) it can be outsourced, it will be outsourced --- there are lots of third-party sites that do a great competition with apple for documentation, especially for swift/swiftui and i get the feeling that apple is maybe conflicted... they want to solve thier problem of documentationm but 1. there are lots of great (albiet scattered) resources on the internet already 2. things change radically year after year (uikit → swiftui, x64 → arm, etc); its hard to maintain a "tome" at apples pace and scale 3. apple is all about effeciency; stopping to write a book when you could be coding or innovating doesnt seem worth it .... its a difficult situation and would probably cost a lot of money and resources, and logistically, seems like it would slow up development quite a bit (even if someone else wrote the books, you still have to coordinate with the devs)...
- deleted 5y ago[deleted]
- travisgriggs 5y agoIsn't the real time most software documentation started going down hill was as the internet became the primary way of distributing and updating software? When software distribution was tied to hardware mediums, it froze snapshots in time, and the documentation thereof could be snapshotted with it (to varying levels of success). Even needed to be. But once it all became primarily net based, it meant the software was always fluid, in motion. Imagine the tech writer approaching a developer now days: "Explain how this works to me" "Ok, right now, it works like this, but we're working on a revised version for next year..." "Sigh. Ok, explain that to me too." "You bet, but make sure and check back with me before you publish, because some things might change yet." It's an irony, that the original dream of "the web", a distributed documentation system, is rendered ever instantly out dated in the realm of software because of the distribution models it eventually enabled. Unintended side effects I guess. As a side anecdote, consider man pages for venerable established Unix commands. Now consider the man pages for newer Unix utilities. IME, the newer features are often under documented and require going to code portals to get detailed/up to date answers.
- ghshephard 5y agoDepends on the version of Unix. OpenBSD considers documentation to be a first class feature of the operating system, and new functionality isn't considered ready for merging and release until the documentation is complete and high quality.
- megameter 5y agoIt speaks to the contradictory nature of software development as it's currently practiced, I think. "What does the software do?" "What do you want it to do? We can add that." "Well, I want to be able to access my old work in a few years, and maybe use it in another program." "I pinky promise that that will happen, and we will make that happen, after we get through all our other customer requests." It's not exactly a new problem that we keep updating software - "bells and whistles" is an old piece of hacker jargon - but there isn't a sense of definite publication now, because there are so many methods of blackboxing in the way, and that's been allowed to take place through the promise of "one more thing" and "surprise and delight" - we only really put up with it through a sense of increasing hype and spectacle. If you have a really firm grasp on what you want the computer to do, you can eliminate just about every application program.
- ineedasername 5y agoIs this a problem in Windows? My dev work doesn't come near OS-specific issues, so I don't know.
- ajarmst 5y ago"nor are the skills of writing good documentation even vaguely similar to those for writing good code". I disagree. Vehemently.
- Endemaj 5y agoAsset Management Companies In UAE https://endemajfunds.com https://endemajfunds.com
- 8bitsrule 5y ago"Inside Macintosh" superb? I was puzzled and then disgusted when I saw that in stores, and realized the difference between Macs and the Apple II. The manual for that machine was a masterpiece ... written for users. The 'revolution' ... obfuscating the OS internals, limiting access to the anointed ... was a tragedy. 'Killing Big Brother' my ass. (It took me a lot of digging - in those pre-web days - to find out what magic numbers to poke, and where to poke, to turn the Mac serial port into a MIDI port.) Anyway, I expected the 'elephant' to be the array of monopoly-busting legislation floating around the Congress right now. Popcorn ready.