[HN Gopher] The Elephant at WWDC
___________________________________________________________________
The Elephant at WWDC
Author : ingve
Score : 341 points
Date : 2021-06-13 13:08 UTC (9 hours ago)
(HTM) web link (eclecticlight.co)
(TXT) w3m dump (eclecticlight.co)
| bob1029 wrote:
| Conversely, 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-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.
| jiggawatts wrote:
| Are you kidding? Seriously, is this a joke?
|
| Literally 99% of anything I search for in Microsoft
| documentation these days lands me in a page where the only
| additional English text is the function definition with spaces
| added between the words! Entire APIs are 100% undocumented, at
| least in this sense. Security-related APIs are totally
| undocumented. APIs critical to disaster recovery are totally
| undocumented. I could go on and on.
|
| It wasn't always like this! The C# standard library documented
| _used to be_ fantastic, with multiple pages of text for pretty
| much every function. Now? It 's hot garbage.
|
| Let me give you an example. Not a _contrived_ example of some
| obscure API that nobody cares about, but a "flagship" feature
| of dotnet core that was heavily advertised recently as a
| significant step forward in its capabilities:
| System.IO.Pipelines
|
| This is a complex, difficult to use API. How is it documented,
| you ask? There's a couple of out-of-date videos showing an
| earlier version that no long matches the current names. There's
| some announcement blog articles. There's _one_ overview page
| that almost -- but doesn 't quite -- cover enough to write a
| useful real-world application. The rest of the documentation
| reads like this: // Gets the MemoryPool<T> to
| use when allocating memory. public
| System.Buffers.MemoryPool<byte> Pool { get; }
|
| (From: https://docs.microsoft.com/en-
| us/dotnet/api/system.io.pipeli... )
|
| I am enlightened! I _understand now_. Before that documentation
| page, I could not figure out that a getter called "Pool"
| returning "MemoryPool" returns a memory pool to use for memory
| allocation. But wow, that documentation really cleared things
| up!
|
| I know I'm being more than a bit snarky, but it's _deserved_.
|
| Microsoft's work is not GNU. It's not truly open source. It's
| not made by volunteers. MSFT is not a charity. In fact, their
| products in general are _very_ expensive. I pay through the
| nose for this! I pay through Windows licensing. I pay through
| Azure hosting costs. I pay through Office 365.
|
| What do I get for this money? Function names with spaces added.
|
| > 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.
|
| That is the _worst_ thing about Microsoft documentation. They
| 've realised that they no longer need to allocate any budget at
| all to technical writers, because people like you will happily
| volunteer your own time to fix something you're already paying
| for with your actual cash money.
|
| Stop.
|
| If you're going to volunteer your time, do it for a charity.
| Write a Wikipedia article or contribute to Linux. Don't use
| your precious time on this Earth to help the world's _second
| biggest_ company for no compensation whatsoever!
| phamilton wrote:
| Azure 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 wrote:
| One 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 wrote:
| Microsoft 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.
| reactspa wrote:
| Just my 0.02:
|
| True, Microsoft has always had extensive documentation.
|
| However, during the Ballmer era, there was tremendous version
| confusion. It was no longer clear which version of software a
| lot of documentation referred to.
|
| I've noticed a huge clean-up in this regard after Satya took
| over. I suspect he got some very competent person to take
| over all the public-facing documentation, to make it more
| user-friendly.
|
| The result: I am willing to trust Microsoft documentation
| again.
| PostThisTooFast wrote:
| Amen. I learned enough to start off in C++ from a thin white
| book from Microsoft about the language. Really excellent.
|
| Not to mention that the Windows help system was better in the
| early '90s than the Mac's is today. Help on the Mac is a
| disgrace, which is why a lot of applications have just
| started delivering a PDF or doing all Web-based doc (which
| sucks when you're trying to work offline) instead of
| bothering with it.
| gambiting wrote:
| I'm a games developer working on some AAA xbox productions
| and I don't think I agree. My #1 impression with Microsoft
| documentation is that you run into a message "error occurred,
| click here to open documentation page", you click on it, only
| to be redirected to a 404 page or simply to MSDN's main
| website.
|
| Like, yes, the pages that exist are usually very well written
| and detailed. But jesus christ, their links even just between
| MSDN pages are constantly broken, if you find an article
| older than 12 months you can be 100% certain nothing on the
| page will work when clicked on. It's like there is a wealth
| of knowledge there, but whoever is in charge of maintaining
| MSDN makes a point of redesiging the entire website every
| year and breaking literally every link in the process.
| dafelst wrote:
| Agreed, the Xbox documentation is hot garbage. They expect
| you to flip flop between the .chm file shipped with the XDK
| and online, but like you say the links are almost always
| broken. On the flip side though the private Xbox dev forums
| are awesome, I find them more useful than the docs.
|
| Sony's PS4/PS5 docs also suck and are a giant pain in the
| ass to get to because they make you allow-list only
| specific IP addresses (a nightmare during the pandemic),
| but at least they are all in one place.
| gambiting wrote:
| Yeah, xbox forums are very very good, and you usually get
| a reply directly from someone on the Xbox Development
| team within few hours. If you ever get a chance to go to
| XFest(assuming they still continue after the pandemic),
| it's really worth going - you get to meet people actually
| working on the hardware and software, collecting some of
| their emails goes a long way when working on a game ;-)
|
| And yes, PS4/PS5 documentation is....lacking. It's all in
| one place and at least easily searchable but most
| functions have descriptions 2 sentences long and you have
| to look in the samples for the actual knowledge of how to
| call something.
| dafelst wrote:
| Haha, yes, direct emails for folks in xbox is very
| useful, the xfest advice is very solid.
|
| I actually went from working at a first party studio
| inside Microsoft to an indie company, so luckily I have
| my network to fall back on. Now I just need to work out
| how to do the same for Sony and Nintendo...
| a_t48 wrote:
| There _used_ to be a Japanese game developers mixer at
| GDC (not sure if it's still around) - I met some folks
| from Nintendo there, though nobody specifically on the
| hardware side. Worth a shot, though. :)
| taftster wrote:
| Right. And this would be _so_ easy to fix too.
| a) crawl your own documentation and find dead links.
| b) monitor 404 errors and track down the source (via
| referer headers, etc.). c) ask the user on the 404
| page what they were hoping for or provide a search menu,
| record it, and have someone manually review. d) add a
| redirect management engine, so you can redirect links that
| you can't/won't ever fix.
| zeusk wrote:
| I'll write a crawler and get this done for CGA docs
| (Compute, Graphics and AI).
|
| Thanks for the tip.
| taftster wrote:
| Sarcastic? I can't tell.
|
| I didn't mean to imply it was trivial, but the concept of
| crawling your own documentation is quite sound and should
| just be part of good document maintenance.
|
| There are some plenty good crawlers already. I'm guessing
| one of them has a 404 report that could hopefully be used
| to find dead links.
| wvenable wrote:
| I agree with both of you -- Microsoft documentation is
| generally excellent and extremely detailed and often more
| than just what you'd get from automatically generating it
| from code comments.
|
| _But_ the tools constantly send you to links that don 't
| work or provide no useful information. It's a very weird
| disconnect. I never trust the "click here to open
| documentation page".
| worik wrote:
| Half right....
| ape4 wrote:
| I've seen this. Also the search on the MSDN website is
| really bad. For some reason it never gets a reasonable
| result. I use google with site:docs.microsoft.com
| alisonkisk wrote:
| Do you really think that's a "philosophy" and not just
| thoughtless careless underinvestment?
| dcow wrote:
| What's the real difference? It's the same with good
| testing. Engineers are expected to operate on timelines and
| meet deadlines that are often not generated by someone who
| values good testing and thorough documentation. If Apple
| wanted good documentation they would have to be comfortable
| with something that was going to take one week now taking
| two weeks and they'd probably need to include willingness
| and ability to document as something they select for when
| hiring. Or they'd have to spin up documentation teams that
| work alongside feature engineers, or something. In almost
| every environment I'm been in, people balk when you force
| them to confront the reality that good quality things take
| time and effort. So I don't think it's just a careless
| "whoops we forgot to tell the engineers to document" type
| of scenario. I think it is fundamental to the fabric of the
| company and those that operate it.
| defaultname wrote:
| I mean, generating a list of classes and their members,
| hierarchies and relationships, with basic annotations, is
| the easiest, most mechanically automated solution possible.
| Apple's bizarre documentation seems like it would take
| significantly more work.
|
| It truly seems philosophical. Someone there thinks this is
| a superior solution.
| Apocryphon wrote:
| Embarrassingly, it's been said that Xamarin's iOS
| documentation is better than Apple's own.
| bryanrasmussen wrote:
| >Microsoft has had superb documentation for decades. They put
| a lot of emphasis on it and the results show.
|
| I remember somewhere between 2006-2009 they did a
| reorganization / reimplementation of their online
| documentation which meant that the menu was always far too
| long to load and sometimes killed the browser I was on.
| Whatever point it was at was the point when I stopped using
| MS technologies as I figured the open source was just as
| well, and if not as well documented, at least trying to read
| the documentation seemed a lot safer.
| fpoling wrote:
| I year ago I worked on media decoding code both on Mac and
| Windows. Documentation for media API sucked on both
| platforms, but it sucked in different ways.
|
| Apple quite frequently left important details and it took me
| few weeks to understand why the decoding code misbehaved in
| one particular case. With Microsoft I run into this only once
| and it was straightforward to fix. Note that in both those
| cases with Apple and Microsoft StackOverflow and similar
| sites was not helpful and even harmful retrospectively since
| that gave wrong direction to dig, but this is another story.
|
| On the other hand Microsoft documentation was more shallower.
| If one knows roughly what to do, then things are OK. But by
| just reading one can not learn how to solve problems. Guides
| were not helpful, as those were at too high level.
|
| Surprisingly with Apple, when they did described API, they
| gave helpful hints what to do next. Plus API was named more
| sensibly.
| nextweek2 wrote:
| > Microsoft has had superb documentation for decades
|
| No, they've had lot's of documentation. That's not the same
| thing. For decades it was very shallow with no examples.
| You'd get an enum list with a half sentence explanation.
|
| The last couple of years they've really upped their game.
| With detailed examples, explanations and even source in
| multiple languages.
|
| To me Qt's documentation was the benchmark, but the latest
| documentation from Microsoft has really caught up.
| LeSaucy wrote:
| Qt5 documentation quality has steadily slid down hill. Any
| new modules they add you essentially have to peruse the
| source to understand what/how/why it works.
| sircastor wrote:
| I had a coworker critical of my position while working
| with Qt when I complained about poor documentation,
| saying that if I needed to know how something worked, I
| should just read the source.
| defaultname wrote:
| "No, they've had lot's of documentation. That's not the
| same thing. "
|
| This kind of snotty reply is always interesting. I've been
| a professional developer for 25 years. For most of those
| years I was deep in the Microsoft platform. C++, Win32 API,
| DirectX, COM+/DCOM, OLE, automation, C# / .NET.
|
| For _decades_ they 've had exhaustive narrative
| documentation that would give huge backgrounders on
| everything. Architectural "how it fits" documentation with
| wonderful diagrams, hierarchies, etc. I could easily find
| _anything_ and jump to specific APIs. _Shitloads_ of
| examples. They clearly have had a great documentation focus
| for a long, long time. Something like the MSDN Library was
| years before its time.
|
| Let me repeat, probably with _way_ more experience in
| saying this, that Microsoft has done documentation well for
| years, and I seldom felt deprived (aside from occasionally
| when they do a restructure and search engines /links go to
| obsolete links). It is specifically in contrast to
| Microsoft's long excellent documentation that I find
| Apple's to be a sad joke.
|
| There is some bizarre tendency in here for people to
| pretend that everything Microsoft does well they've only
| done well for most recent history, as if this is some sort
| of odd proselytizing and naysayers should realize that
| everything has _changed_.
| fortran77 wrote:
| > This kind of snotty reply is always interesting
|
| It's a typical HN Apple Zealot tactic. They simply lie to
| boost their cult.
| lallysingh wrote:
| Nope. They've always had a lot of documentation. It's
| often been crap. I've been developing for MS platforms
| off and on since Win3.1, and have constantly dealt with
| cycles of "knowing API function A requires you understand
| what an X is, linked to function B, which only discusses
| X in terms of function A.". They write a lot, but it's
| not good. It's like a Hollywood western set where your at
| just the fronts of buildings. Lots of them, no depth.
|
| You always have to get a 3rd party book to figure this
| crap out... if you can find one. And if you're off and
| on, then you're constantly playing this game every few
| years.
|
| Frankly the X11 books out of O'Reilly are my standard for
| "good."
| eropple wrote:
| I don't agree with this at all. I spent a solid decade
| doing predominantly Windows development and I haven't
| felt the need to buy a book on any Microsoft topic since,
| like - "learn Visual Basic 5". While they probably had a
| good stretch of years from like after VS2008 until maybe
| after VS2015 where the documentation was clearly not a
| focus, I've never had any trouble learning first-and-
| foremost from the documentation and have often used MSDN
| as a good example of _not_ needing to already understand
| the entire topic to benefit from first-party
| documentation on that topic.
| throwaway894345 wrote:
| > This kind of snotty reply is always interesting. I've
| been a professional developer for 25 years.
|
| I didn't interpret it as "snotty" (not beyond the norm
| for this forum, anyway). Could have been worded better,
| but charitable interpretation is an HN guideline.
|
| > There is some bizarre tendency in here for people to
| pretend that everything Microsoft does well they've only
| done well for most recent history, as if this is some
| sort of odd proselytizing and naysayers should realize
| that everything has changed.
|
| Or perhaps the parent just disagrees with you on merit
| and there is no nefarious underlying motive? In my
| experience at least, Microsoft's ethos and behavior has
| improved significantly in the last ~decade with respect
| to openness, developer friendliness, attitude toward open
| source, product quality, etc. It seems clear to me that
| there is some broad cultural change at MS and it seems
| plausible that it could affect documentation quality as
| well.
|
| Personally, I don't have a dog in this documentation
| fight, but your comment seems unjustifiably angry.
| defaultname wrote:
| It isn't that it's nefarious but rather that people who
| adopted Microsoft late rationalize that the company has a
| maligned history (some deserved, some not) by declaring
| that everything is _different_ now. This appears in
| conversation after conversation where some current
| Microsoft enthusiast declares that everything was crap,
| but now it 's wonderful.
|
| But a lot of things were already very good to excellent.
| I mean, one of the things you mentioned was developer
| friendliness yet the company has forever had industry
| leading developer relations. They've always had great
| documentation (there are going to be some developers who
| will still struggle and fail, but that isn't the fault of
| the documentation which can only drag them so far). SQL
| Server has been a great product for literally decades. NT
| was actually a great OS for the era and vis-a-vis its
| contemporaries. Microsoft has always been very "open" in
| fields where they are struggling. And on and on.
|
| They did a lot of great things in the past along with bad
| things. And right now they're doing great things along
| with bad things. Every org is a mixed bag.
| p_l wrote:
| arguably it's been the last decade that documentation
| from MS suffered, specifically around the time that their
| software stopped shipping with CHM&co files and started
| opening web pages.
|
| But they are quite actively rebuilding from the
| switchover. I still miss CHM.
| thrower123 wrote:
| That documentation exists at all has been enough to put
| MSDN at the top for the past couple decades.
|
| Win32 doc has always been good, back into the 90s. Some of
| the Sharepoint and Lync and when they were starting to open
| source all the things has been lacking. There was also that
| stretch where they axed all the QA department... Shudder...
| userbinator wrote:
| Microsoft used to be great at documentation. Then the
| MSDN->docs.microsoft.com "migration" (what for?) destroyed a
| lot of old links, and mysteriously introduced errors that
| weren't there before, like this page:
|
| https://docs.microsoft.com/en-us/windows/win32/api/wininet/n...
|
| (Hint: what does the function return? Countless pages of
| function references got their return types set to "void" for
| some inexplicable reason. If that isn't incompetence or malice,
| I don't know what.)
|
| _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._
|
| I actually asked about that error before on their GitHub, but
| they basically said they'll handle each case as it gets raised.
| No, I'm _not_ going to fix docs that you broke. It looks like
| MS basically got rid of all their actual documentation writers
| and are now trying to rely free labour from the "community".
| cxr wrote:
| > 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
|
| We had better than that 10+ years ago: actual wikis. We've
| regressed quite a bit. Even developer.mozilla.org has gone
| backwards. Had devmo not been a wiki, I'd have never poured so
| much effort into the JavaScript docs between 2006-2008.
| z77dj3kl wrote:
| Yeah, I've noticed this too. Most of the time when you look up
| something gRPC related, the first links are for some of
| Microsoft's gRPC documentation!
|
| gRPC is one of those projects that I'm not sure if Google
| really wants uptake or if it's just a dump as a means to open
| source other things they want uptake in (GCP client libraries,
| tensorflow, etc). The documentation is awful.
| alisonkisk wrote:
| Idoubt google care if you use grpc for its own sake, unless
| adopting it for its own sake helps you migrate your important
| tech to google-preferred versions.
| meibo wrote:
| .NET documentation is incredible, not just for the language but
| also the APIs. It's such a joy to work with and even complex
| concepts seem to be explained very thoroughly.
|
| It gets a bit uglier once you cross into WINAPI, COM, etc., but
| Apple's is still not even close to being a match.
| the_only_law wrote:
| > It gets a bit uglier once you cross into WINAPI, COM, etc.,
| but Apple's is still not even close to being a match.
|
| I feel like .NET documentation has _significantly_ improved.
| It wasn 't that long ago when I had no idea how to find the
| documentation from the MSDN home page and had to rely on
| search engines, but outside I agree. Microsoft's
| documentation gets a bit rough. Most recently, I found the
| NDIS documentation unbearable, with broken links and links to
| 5.x versions. Additionally, I was trying to find the
| documentation on OLE, and google kept leading me to MFC
| specific stuff, which was not what I was looking for.
| tonyedgecombe wrote:
| Some of the older stuff seems to be getting worse. I was
| searching for information on Active Scripting and it
| appeared that documents I had used in the past had
| disappeared. I know nobody is implementing this from
| scratch but old code needs to be maintained.
| amelius wrote:
| Strangely, the best documentation I've seen so far has been
| PHP. The only reason: because developers could comment right
| below the documentation. It's like having StackOverflow right
| there, in the documentation page.
|
| (Note: I haven't touched PHP since 20 years or so, so not sure
| if it's still the case).
| HoppyHaus wrote:
| It still is the case, and the documentation itself has
| improved greatly over time. PHP is one of the few programming
| languages that I feel can be used using only the official
| documentation (with the comments, of course)
| traspler wrote:
| When 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.
| smoldesu wrote:
| I despise Microsoft's products for the most part, but I can't
| lie: their documentation kicks ass. The C++ documentation is
| some of the nicest around.
| [deleted]
| aledalgrande wrote:
| Yeah documentation looks fine and all for the LinkedIn API,
| until you have to deal with failures because of outdated
| validations or missing explanations.
| [deleted]
| jitix wrote:
| Even back in 2019 I was suggesting everybody to read API
| development design patterns from the Microsoft documentation.
| It was clean, neutral (not .net focused) and easy to
| understand.
|
| Microsoft under the new management has really turned around and
| become a "good" tech company (relative to google and Facebook).
| DaiPlusPlus wrote:
| The "Patterns and Practices" stuff on MS' site was mostly
| written in the mid-2000s (when SOAP was a thing). A lot of
| other content came from MSDN Magazine contributing authors,
| but that's discontinued now - I'm curious what drives their
| whitepapers now.
| DenverCode wrote:
| I am currently a year away from graduating and we haven't
| touched documentation once - simply commenting lines of code
| during DS&A.
|
| Does anyone have any recommendations for resources to learn or
| is it simply reading through documentation akin to that
| Microsoft link and others like Stripe?
| deathanatos wrote:
| Huh, I have a different impression. Take this doc, that I was
| staring at the other day: https://docs.microsoft.com/en-
| us/rest/api/containerregistry/... ; it is for listing manifests
| in an ACR repo.
|
| The "orderby" query parameter is documented as "orderby query
| parameter". It is secretly an enum; the values are things like
| "time_asc" and "time_desc".
|
| Later, take the response. "lastUpdateTime" is documented as
| "Last update time". It's documented as a string, which while
| technically correct (at the JSON level, yes, it is a string,
| ish), is wrong. It's an RFC 3339 datetime -- I think1 -- but
| it's also wrong because it is -- bizarrely -- optional. I
| actually don't know what sets it, and I have no examples of it
| being set and the docs don't help.
|
| I could also refer one to their documentation about the various
| performance characteristics of various Azure VM types. Some VM
| types _just aren 't listed_, so if you're curious about those,
| good luck, I guess? Run them yourself?
|
| We've also hit things like various tri-bools. IIRC, whether
| you're on a paid SKU for AKS is a weird tribool of sorts. The
| field has two values, represented by three values: "Free"
| (meaning free), "Paid" (meaning paid) and the field simply not
| being present at all, meaning the same as "Free". Not only is
| the chosen representation terrible, that it is this way is
| undocumented.
|
| 1I don't have a counter example yet, at least...
| fortran77 wrote:
| Apple documentation has been awful for decades. There's so much
| history and insider knowledge you need to write good desktop
| MacOS applications.
|
| And Microsoft documentation has been excellent for decades.
| Even pre-Internet with MSJ and Microsoft press.
| justinclift wrote:
| Conversely, when looking through the Azure documentation last
| week for much of their Python SDK libraries... it's a joke.
|
| They have _tonnes_ of new-user intro stuff and similar. Super
| impressive at first look, but once you're past that and need to
| dig into complicated things it's all undocumented.
|
| Even most of the auto-generated pages in their Python SDK
| function lists are just "Header -> empty space where content
| should be -> footer". And nothing else.
|
| ... and lets not get started on the docs for Microsoft Graph.
| :/
| GordonS wrote:
| I'm a heavy user of Azure, and I have 2 general issues with
| their docs.
|
| Firstly the documentation for the various SDK is often an
| issue, because it's often _behind_ the latest release of the
| SDK.
|
| For .NET libraries especially, there is just so much _churn_
| that they obviously struggle to keep the docs updated.
|
| And then secondly, as you say, there just aren't enough
| examples beyond the most trivial.
| ChrisMarshallNY wrote:
| DISCLAIMER: 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/
|
| _> 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
|
| I've written about my own experience and practice, in regards to
| documentation[2].
|
| [2] https://littlegreenviper.com/miscellany/leaving-a-legacy/
| zepto wrote:
| > 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.
| [deleted]
| traspler wrote:
| The 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 wrote:
| New 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 wrote:
| > 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...
| m12k wrote:
| > 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.
| Benjamin_Dobell wrote:
| I 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 wrote:
| 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.
| shadowfiend wrote:
| 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.
| millerm wrote:
| +1 Nicely explained.
| mr_tristan wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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.
| cratermoon wrote:
| > 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.
| rubicon33 wrote:
| > 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 wrote:
| 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 wrote:
| I used this book and I found it to be excellent.
|
| https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_d
| t_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 wrote:
| Very eloquently said, couldn't agree more.
| jtdev wrote:
| A good coder does not a good technical document writer make.
| bombcar wrote:
| They 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 wrote:
| I 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 wrote:
| I 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).
| rleigh wrote:
| I 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.
| valuearb wrote:
| Good 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 wrote:
| I 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.
| Spooky23 wrote:
| That'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.
| thesuperbigfrog wrote:
| Apple'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 wrote:
| Apple'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 wrote:
| Everyone 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 wrote:
| I 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.
| xwdv wrote:
| Disagree. 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 wrote:
| I 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.
| the_arun wrote:
| Does `docc` works only for Swift? Could we use it for other
| programming languages? eg. Java
| josephcsible wrote:
| Basically 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 wrote:
| Javadoc seems very restrictive in terms of user interface,
| search etc., It is also not interactive. Hence, looking for
| something better.
| luckyorlame wrote:
| Writing code and writing documentation are completely linked, if
| you can't do one, you probably can't do the other.
| merrywhether wrote:
| Isn'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.
| Grimm1 wrote:
| I 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 wrote:
| Can you recommend a book or course for improving ones ability
| to write good technical documentation?
| cratermoon wrote:
| Not 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
| spockz wrote:
| Can 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.
| Grimm1 wrote:
| I think it may just be easier to share where I got any of my
| lessons from.
|
| https://developers.google.com/tech-writing
|
| Google has two short courses about 6 hours total or so that
| seemed a good consistent basis for me as an engineer writing
| documentation.
|
| I'm not sure if it's going to answer your question on what
| types of documentation you will need though and how to make
| it feel less inadequate just how you as an individual can
| write better documentation.
| jeffreyrogers wrote:
| I'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 wrote:
| I 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/
| leoc wrote:
| Wasn't the original _Inside Macintosh_ supposedly a nightmare?
| Did it improve dramatically over the lifetime of (classic) MacOS?
| johndoe0815 wrote:
| The 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)...
| bluenose69 wrote:
| I 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.
| microtherion wrote:
| The original Inside Macintosh was quite decent. The main
| problem, I think, was that it was hard to understand just
| pieces of it; if you read it cover to cover it was pretty good.
| But by the time Inside Macintosh VI rolled around with its 1750
| pages to cover the System 7 additions, that approach had run
| its course.
|
| Apple then reorganized and rewrote the entire documentation
| along functional lines, producing separate, smaller, volumes
| for e.g. Memory, File Management, etc. That New Inside
| Macintosh series was, in my opinion, the highest quality
| documentation Apple ever produced.
| ec109685 wrote:
| It was also assembly and pascal for the longest time, even when
| most folks had switched over to C.
|
| The heyday was an app that had digitized all the documentation
| and iirc the code examples were in C. It had hyperlinks between
| pages. Quite nice pre web reference material.
|
| Their code examples were also helpful, but things like low
| level double buffered sound recording or high performance
| animation was left as an exercise to the reader.
| afavour wrote:
| This 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/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.
| seanalltogether wrote:
| My latest one was the documentation for slicing up strings. All
| the example code for string.prefix() string.suffix()
| string.subscript() has code examples using arrays.
|
| https://developer.apple.com/documentation/swift/string/28948...
| lilyball wrote:
| New APIs introduced in betas often don't have documentation
| until later. When working with beta APIs, read the header.
| tayistay wrote:
| Sometimes 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. */
| afavour wrote:
| That's very useful information that would be very useful i
| the docs! Thank you. I'm a little confused as to how it
| differs from the existing method for loading data:
|
| https://developer.apple.com/documentation/webkit/wkwebview/1.
| ..
|
| but I suppose it allows for more customisability. Marking the
| existing one as deprecated would go a long way to solving the
| mystery. Assuming that's even correct! This is where
| documentation beyond literally only detailing what the API
| does would be great.
| Fordec wrote:
| Wow, 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 wrote:
| Not 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.
| andrekandre wrote:
| my 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)...
| hermanradtke wrote:
| One 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 wrote:
| Off topic: I didn't know the Rust mascot was named Ferris.
| That's a lovely play on words.
| giantrobot wrote:
| From 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 wrote:
| > 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 that others?
| johndoe0815 wrote:
| The 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...
| Pulcinella wrote:
| The documentation for Metal (Apple's graphics API) is quite
| extensive, especially compared to the documentation for other
| frameworks/APIs and always seems to get 4-6+ videos at WWDC. I've
| also heard that Apple sends Metal developers to big graphical
| software developers to provide extensive help.
|
| For whatever reason Metal seems like it receives a lot of
| resources and encouragement that the other API teams do not. I am
| definitely not saying that the Metal team shouldn't receive this
| treatment, I'm just wondering why Apple seems reluctant to just
| buy its way out of this problem. They have the money. They could
| hire people to e.g. update all their old programming guides and
| include examples with Swift (most like the CollectionView guide
| are only in Obj-C). (While I'm spending Apple's money, they might
| as well just pay developers like the Sketch team whatever it
| takes to get Sketch and other Mac apps on the iPad).
| traspler wrote:
| What 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 wrote:
| I'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
| moralestapia wrote:
| Something 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.
| tpush wrote:
| > 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."
| moralestapia wrote:
| Haha, amazing.
| the-dude wrote:
| And 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 wrote:
| Could you please, then, point me to a creditable source
| regarding what 'powerd' is?
| the-dude wrote:
| No, I couldn't be bothered either.
| [deleted]
| wux wrote:
| You can use the 'man' command in Terminal to pull up the
| man page (see: 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."
| astrange wrote:
| Besides the man page, the places to look are "spindump -stdout"
| and "log stream".
| bluenose69 wrote:
| I just watched
| 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 wrote:
| > 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 wrote:
| Apple's comment system has existed for much longer than
| Swift.
|
| https://en.wikipedia.org/wiki/HeaderDoc
| ChrisMarshallNY wrote:
| I 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/
| Grustaf wrote:
| The 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.
| hamiltont wrote:
| Passion 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 wrote:
| Just 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 ...
| 3grdlurker wrote:
| It'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.
| mooreds wrote:
| I 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
|
| 1: https://www.oreilly.com/library/view/the-new-
| kingmakers/9781...
| mooreds wrote:
| Incidentally, if you are looking for a mental model around tech
| documentation, I haven't found a better one than this:
| https://diataxis.fr/ which discusses tutorials, how-to guides,
| technical reference and explanation.
| lanstin wrote:
| I 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.
| djoldman wrote:
| _Generally_ 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 wrote:
| What'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.
| throw14082020 wrote:
| this 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 wrote:
| You 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 wrote:
| The 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 wrote:
| > 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 wrote:
| Aren'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.
| brandonmenc wrote:
| I 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.
| stephencanon wrote:
| > 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 wrote:
| There'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.
| kace91 wrote:
| >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.
| worik wrote:
| I 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
| jeremymcanally wrote:
| This 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.
| chipotle_coyote wrote:
| While I haven't worked at Apple, I've worked in technical
| documentation at other places (and still am) and worked with
| engineers, and I can't help but push back a bit on your
| implicit assertion that better tooling for engineers is going
| to help Apple make better documentation. Having coding and docs
| be so decoupled that you're not able to make good documentation
| is not a tooling problem -- it's an internal communication
| problem.
|
| From what I can see and what others have mentioned, DocC is an
| Apple-blessed version of existing community tools like Jazzy.
| Apple _could_ have been using that already, and indeed the
| engineers could have been using any number of docs-in-comments
| systems to generate basic API docs that could have been then
| forwarded to the docs team.
|
| But even if they _didn 't_ have that, it is still up to the
| engineers to get that information to the docs team somehow, and
| still up to the docs team to ensure that new APIs and
| frameworks are documented. Full stop. _Someone,_ probably a PM
| somewhere, should have the responsibility to make sure those
| things happen _in tandem._ For example, new features and new
| frameworks could go in a issue tracking system, those issues
| have descriptions from engineers of at least the barebones
| basics, the docs team has access to those issues, and separate
| documentation issues are created and linked to those issues.
| And lack of _basic_ documentation should arguably be treated as
| a release blocker. I am sure there are a lot of engineers in
| the audience raising their hands in protest at that, but when
| you 're talking about an API or an SDK, the documentation is
| essentially your user interface. You don't need to have the
| equivalent of the multi-volume _Inside Macintosh_ documentation
| ready to go on shipping day, but you need to have a basic Jazzy
| /Javadoc-style reference and an overview doc on day one.
|
| I don't doubt Apple's documentation team is "small but mighty,"
| but there seems to be something fundamentally broken in Apple's
| process. If DocC helps, that's great, but at best it's just a
| start.
| BossingAround wrote:
| > 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 wrote:
| Many 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.
| cratermoon wrote:
| If 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.
___________________________________________________________________
(page generated 2021-06-13 23:00 UTC)