4 ms·

Already a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485436674?mt=12 https://apps.apple.com/us/app/a-companion-for-swiftui/id1485... No a

Already a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485436674?mt=12 https://apps.apple.com/us/app/a-companion-for-swiftui/id1485... No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.

doyouevensunbro 6y ago
It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.
- piva00 6y ago
  A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
  - ethbr0 6y ago
    Just hire Microsoft's people. Not even joking. https://docs.microsoft.com/en-us/dotnet/api/system.string.substring?view=net-5.0 https://docs.microsoft.com/en-us/dotnet/api/system.string.su...
    - jjkaczor 6y ago
      For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure, Sun replied - but first you have to buy a $30,000 server... Thankfully, .NET hit public beta about then and I have never looked back.
      - wlesieutre 6y ago
        There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers
        ethbr0 6y ago
        It's mocked, but the underlying observation is astute. In the personal computing world, first parties can't build enough user software. Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years. And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well. Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.
        jonhendry18 6y ago
        Apple used to be better about developers, I think, back 2000-2010 or so.
        wlesieutre 6y ago
        Mocked at the time, but looking back it sounds pretty good. Maybe Apple needs a Steve Ballmer.
        int_19h 6y ago
        If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps. It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.
      - sirmarksalot 6y ago
    - markdoubleyou 6y ago
      For Microsoft it depends on when the docs were written. The MS docs from the late '90s through about 2015 were stellar. For example, look at the Windows Sockets docs[1], which came out of that era. Here you see information architects working at the height of their power: Content is broken up into conceptual ("About Winsock"), task-based ("Using Winsock"), and reference ("Winsock Reference") topics. They were doing this kind of structured documentation before DITA was a thing. It's a pain in the ass to produce content this way, but the results are wonderful. Then came .NET Core: a fast-moving, community-driven effort, where the philosophy seems to be to get it working and then scribble down some docs later. The result tends to be a huge wall of text with conceptual and sample topics jammed together ([2]), and you're lucky if the API reference gives you anything beyond parameter names. Azure docs suffer from a different problem. It seems they've tried to apply some kind of rough information architecture, but the quality isn't great. I've looked at the GitHub history of some of the shoddier topics, and they're often written by junior Product Managers who are fresh out of college. I encounter a lot of imprecise, colloquial English describing out-of-date screenshots. I don't mean to belittle the people who work on .NET Core and Azure. There's a ton of content that needs to be written for these products, and it's a thankless task for the devs & PMs who do the heavy lifting now. I'd really like to see some dedicated technical writers come in and bring the quality back up to their old standards. [1] https://docs.microsoft.com/en-us/windows/win32/winsock/windows-sockets-start-page-2 https://docs.microsoft.com/en-us/windows/win32/winsock/windo... [2] https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-5.0 https://docs.microsoft.com/en-us/aspnet/core/fundamentals/ro...
      - tasogare 6y ago
        I use C# daily and most of the time the doc is fine. I agree that sometimes dotnet core docs are a bit messy and frustrating, but still quite good and useful.
  - Spivak 6y ago
    It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.
    - chipotle_coyote 6y ago
      Well, not everyone who is qualified to write good documentation wants to work on the code, nor would they necessarily be as good at writing code as they are at writing documentation. If you're writing API documentation, you need to be enough of a coder to understand what the engineers are talking about -- and what they aren't talking about but really should be! -- but that doesn't mean you need to be coding at a level where you could have a career writing apps built on that API, let alone coding at a level where you could have a career implementing the API itself. It's the "culture that rewards and values the work" that's really the issue, I suspect. Apple certainly used to have a culture of good documentation, and I know they've hired good writers, technical and otherwise, over the years. It's actually kind of difficult to explain why their docs are the way they are, other than just not putting any real priority on the necessary work.
    - jyounker 6y ago
      This. Developers aren't getting credited or promoted for writing documentation, or assisting in the process.
- dgritsko 6y ago
  I don't think this truism actually holds weight. Some engineers don't want to write documentation, sure. Maybe even most don't - but some actually do enjoy the process of writing good documentation, and they find satisfaction in creating knowledge artifacts that make their code easy to understand and use. It's not enough to just find these engineers, however - they need organizational support so that they have the right tools to create and share good documentation, and are appropriately encouraged to do so.
- jonhendry18 6y ago
  You have to give them time to write it, too.
- RockmanZero 6y ago
  wrong! bad engineers don’t want to write documentation
SilasX 6y ago
Reminds me -- it used to be that I could plug my Macbook air into a monitor and arrange my windows, and it would return them to that position whenever I'd disconnect and come back. That feature vanished as of ~2018 and you have to buy some app to get it back.
- tidbits 6y ago
  My Macbook pro still does this. Granted, it's a little wonky. If you alter the window in any way while disconnected then it might not return to the original location. It also doesn't preserve any new desktop environments created on the external display.
alblue 6y ago
They actually have a department to write the documentation. The problem is that it’s a separate department from the people who design the libraries themselves, which means instead of having high quality documentation throughout, you only get the documentation that the doc team had time to write. It’s why most of the APIs are minimal at best in terms of documents. While the level of documentation that exists is usually pretty good, the sad fact is that most documentation doesn’t exist, and it’s entirely due to the fact that they are handled by developers/documentors separately. If you had developers documenting in-situ in the code, instead of WWDC slides, then it would be a lot better.

doyouevensunbro 6y ago

It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.

piva00 6y ago
A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
- ethbr0 6y ago
  Just hire Microsoft's people. Not even joking. https://docs.microsoft.com/en-us/dotnet/api/system.string.substring?view=net-5.0 https://docs.microsoft.com/en-us/dotnet/api/system.string.su...
  - jjkaczor 6y ago
    For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure, Sun replied - but first you have to buy a $30,000 server... Thankfully, .NET hit public beta about then and I have never looked back.
    - wlesieutre 6y ago
      There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers
      - ethbr0 6y ago
        It's mocked, but the underlying observation is astute. In the personal computing world, first parties can't build enough user software. Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years. And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well. Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.
        jonhendry18 6y ago
        Apple used to be better about developers, I think, back 2000-2010 or so.
        wlesieutre 6y ago
        Mocked at the time, but looking back it sounds pretty good. Maybe Apple needs a Steve Ballmer.
        int_19h 6y ago
        If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps. It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.
    - sirmarksalot 6y ago
  - markdoubleyou 6y ago
    For Microsoft it depends on when the docs were written. The MS docs from the late '90s through about 2015 were stellar. For example, look at the Windows Sockets docs[1], which came out of that era. Here you see information architects working at the height of their power: Content is broken up into conceptual ("About Winsock"), task-based ("Using Winsock"), and reference ("Winsock Reference") topics. They were doing this kind of structured documentation before DITA was a thing. It's a pain in the ass to produce content this way, but the results are wonderful. Then came .NET Core: a fast-moving, community-driven effort, where the philosophy seems to be to get it working and then scribble down some docs later. The result tends to be a huge wall of text with conceptual and sample topics jammed together ([2]), and you're lucky if the API reference gives you anything beyond parameter names. Azure docs suffer from a different problem. It seems they've tried to apply some kind of rough information architecture, but the quality isn't great. I've looked at the GitHub history of some of the shoddier topics, and they're often written by junior Product Managers who are fresh out of college. I encounter a lot of imprecise, colloquial English describing out-of-date screenshots. I don't mean to belittle the people who work on .NET Core and Azure. There's a ton of content that needs to be written for these products, and it's a thankless task for the devs & PMs who do the heavy lifting now. I'd really like to see some dedicated technical writers come in and bring the quality back up to their old standards. [1] https://docs.microsoft.com/en-us/windows/win32/winsock/windows-sockets-start-page-2 https://docs.microsoft.com/en-us/windows/win32/winsock/windo... [2] https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-5.0 https://docs.microsoft.com/en-us/aspnet/core/fundamentals/ro...
    - tasogare 6y ago
      I use C# daily and most of the time the doc is fine. I agree that sometimes dotnet core docs are a bit messy and frustrating, but still quite good and useful.
- Spivak 6y ago
  It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.
  - chipotle_coyote 6y ago
    Well, not everyone who is qualified to write good documentation wants to work on the code, nor would they necessarily be as good at writing code as they are at writing documentation. If you're writing API documentation, you need to be enough of a coder to understand what the engineers are talking about -- and what they aren't talking about but really should be! -- but that doesn't mean you need to be coding at a level where you could have a career writing apps built on that API, let alone coding at a level where you could have a career implementing the API itself. It's the "culture that rewards and values the work" that's really the issue, I suspect. Apple certainly used to have a culture of good documentation, and I know they've hired good writers, technical and otherwise, over the years. It's actually kind of difficult to explain why their docs are the way they are, other than just not putting any real priority on the necessary work.
  - jyounker 6y ago
    This. Developers aren't getting credited or promoted for writing documentation, or assisting in the process.
dgritsko 6y ago
I don't think this truism actually holds weight. Some engineers don't want to write documentation, sure. Maybe even most don't - but some actually do enjoy the process of writing good documentation, and they find satisfaction in creating knowledge artifacts that make their code easy to understand and use. It's not enough to just find these engineers, however - they need organizational support so that they have the right tools to create and share good documentation, and are appropriately encouraged to do so.
jonhendry18 6y ago
You have to give them time to write it, too.
RockmanZero 6y ago
wrong! bad engineers don’t want to write documentation

SilasX 6y ago

Reminds me -- it used to be that I could plug my Macbook air into a monitor and arrange my windows, and it would return them to that position whenever I'd disconnect and come back. That feature vanished as of ~2018 and you have to buy some app to get it back.

tidbits 6y ago
My Macbook pro still does this. Granted, it's a little wonky. If you alter the window in any way while disconnected then it might not return to the original location. It also doesn't preserve any new desktop environments created on the external display.

alblue 6y ago

They actually have a department to write the documentation. The problem is that it’s a separate department from the people who design the libraries themselves, which means instead of having high quality documentation throughout, you only get the documentation that the doc team had time to write. It’s why most of the APIs are minimal at best in terms of documents. While the level of documentation that exists is usually pretty good, the sad fact is that most documentation doesn’t exist, and it’s entirely due to the fact that they are handled by developers/documentors separately. If you had developers documenting in-situ in the code, instead of WWDC slides, then it would be a lot better.