4 ms·

Sure that applies to software development, but does it really apply to writing documentation? The articles currently on the developer page could be split up eve

Sure that applies to software development, but does it really apply to writing documentation? The articles currently on the developer page could be split up evenly between a team and be worked on simultaneously.

lapcat 3y ago
Writing documentation requires communication and collaboration with engineering. As you add people to an organization, you also add meetings, bureaucracy, and various other encumbrances. Not to mention that the technology to be documented needs to be done or done-ish, which is difficult when you're shipping major updates yearly! Besides, how large do you think the talent pool is of good documentation writers? I would estimate that it's actually harder to find good technical doc writers than it is to find good programmers. 1) The minimum qualifications for a good API doc writer is practical experience programming with the technology to be documented. That already narrows the field significantly. You can't just a hire a comp sci grad straight out of college. 2) Indeed, a comp sci grad straight out college probably wouldn't want the job anyway. A lot of people aspire to be programmers, because it seems cool, fun, and has excellent compensation. Not many people aspire to become doc writers as a career. 3) The compensation for doc writers is generally lower than for programmers, so if you're already an experienced programmer per 1, then why would you take a step down? 4) The natural retort is going to be, "Just pay doc writers more!" But that's not going to work for several reasons. First, the programmers will be unhappy if the doc writers are paid more than them. Second, companies don't value doc writers as much. Third, once you get off the programmer career track and write docs, it can be difficult or impossible to get back on the programmer career track if you ever want or need to leave Apple. In general, the market is not huge or lucrative. What you tend to get for documentation writers, then, is often older programmers who are starting to experience age discrimination, finding it harder to get a programming job, so they settle for writing API documentation. But that's not a huge pool of available workers.
- Dylan16807 3y ago
  The way you describe the problem, it sounds like paying them more fixes things and the objections to paying them more are wrong. And as far as the "career track" aspect goes, have them keep coding part of the time and keep calling them a programmer.
  - lapcat 3y ago
    > The way you describe the problem, it sounds like paying them more fixes things and the objections to paying them more are wrong. It sounds like you have a reading comprehension problem? > And as far as the "career track" aspect goes, have them keep coding part of the time and keep calling them a programmer. 1) You're missing the part where the majority of programmers don't want to be doc writers, aren't qualified to be doc writers, and aren't good at being doc writers. 2) It's not as simple as having them "keep coding part of the time", because the standards for hiring a coder are different from the standards of hiring a doc writer. Apple wouldn't necessarily hire the same person to do both. It could be a rare situation where Apple would consider the same person to be good enough for both jobs. This is like saying of an American football team, "Why not just have the quarterback play defense part of the time?" Remember, the point of this is to produce high quality docs. Quality over quantity. Apple is already churning out low quality docs.
    - eviks 3y ago
      What kind of mythical quality is you imagine required to add examples to documentation??? > Apple is already churning out low quality docs. The article listed some stats where Apple is not churning out enough docs. So there isn't even quantity
      - lapcat 3y ago
        > What kind of mythical quality is you imagine required to add examples to documentation??? I can see that you have no respect for the difficulty of writing good documentation.
        3y ago
- eviks 3y ago
  Most of the issues you've described have nothing to do with the "mythical man-nonth thinking", so it would indeed be possible to just throw more resources at the problem And the talent pool at the level of a single company is practically infinite unless you indeed introduce artificial constraints like not wanting to pay to tap into that wide pool
  - lapcat 3y ago
    > Most of the issues you've described have nothing to do with the "mythical man-nonth thinking" Hence the "Besides..." > And the talent pool at the level of a single company is practically infinite unless you indeed introduce artificial constraints like not wanting to pay to tap into that wide pool I just explained how that's untrue, and it feels like you completely ignored what I said. You can't just say that Apple is "a single company" like any other company. Apple is the largest platform vendor in the world. How many other single companies have platforms like iOS, macOS, watchOS, tvOS, and now VisionOS? How many other single companies have effectively two bespoke programming languages, Swift and Objective-C, much less one? Perhaps only Google and Microsoft are comparable in their massive need for platform docs.
    - eviks 3y ago
      >You can't just say that Apple is "a single company" like any other company. Apple is the largest platform vendor in the world. The world is HUUUUGE (even limiting by language), so not only can I say "a single company", I can raise it to the level of "a single tiny company", especially when it comes to such a small scale issue > How many other single companies have platforms ... bespoke programming languages How does it matter? There are gazillions of educated people in the world with all the skills for a couple of order of magnitudes more languages than just 2! And it's especially preposterous making this arguments after waves of layoffs in the tech sector And you can't reject a simple solution "just pay more" with "companies don't value doc writers": that explains why they don't hire enough people/don't care about the quality of their output, not that there are some inherent talent pool limitations
      - 3y ago

lapcat 3y ago

Writing documentation requires communication and collaboration with engineering. As you add people to an organization, you also add meetings, bureaucracy, and various other encumbrances. Not to mention that the technology to be documented needs to be done or done-ish, which is difficult when you're shipping major updates yearly! Besides, how large do you think the talent pool is of good documentation writers? I would estimate that it's actually harder to find good technical doc writers than it is to find good programmers. 1) The minimum qualifications for a good API doc writer is practical experience programming with the technology to be documented. That already narrows the field significantly. You can't just a hire a comp sci grad straight out of college. 2) Indeed, a comp sci grad straight out college probably wouldn't want the job anyway. A lot of people aspire to be programmers, because it seems cool, fun, and has excellent compensation. Not many people aspire to become doc writers as a career. 3) The compensation for doc writers is generally lower than for programmers, so if you're already an experienced programmer per 1, then why would you take a step down? 4) The natural retort is going to be, "Just pay doc writers more!" But that's not going to work for several reasons. First, the programmers will be unhappy if the doc writers are paid more than them. Second, companies don't value doc writers as much. Third, once you get off the programmer career track and write docs, it can be difficult or impossible to get back on the programmer career track if you ever want or need to leave Apple. In general, the market is not huge or lucrative. What you tend to get for documentation writers, then, is often older programmers who are starting to experience age discrimination, finding it harder to get a programming job, so they settle for writing API documentation. But that's not a huge pool of available workers.

Dylan16807 3y ago
The way you describe the problem, it sounds like paying them more fixes things and the objections to paying them more are wrong. And as far as the "career track" aspect goes, have them keep coding part of the time and keep calling them a programmer.
- lapcat 3y ago
  > The way you describe the problem, it sounds like paying them more fixes things and the objections to paying them more are wrong. It sounds like you have a reading comprehension problem? > And as far as the "career track" aspect goes, have them keep coding part of the time and keep calling them a programmer. 1) You're missing the part where the majority of programmers don't want to be doc writers, aren't qualified to be doc writers, and aren't good at being doc writers. 2) It's not as simple as having them "keep coding part of the time", because the standards for hiring a coder are different from the standards of hiring a doc writer. Apple wouldn't necessarily hire the same person to do both. It could be a rare situation where Apple would consider the same person to be good enough for both jobs. This is like saying of an American football team, "Why not just have the quarterback play defense part of the time?" Remember, the point of this is to produce high quality docs. Quality over quantity. Apple is already churning out low quality docs.
  - eviks 3y ago
    What kind of mythical quality is you imagine required to add examples to documentation??? > Apple is already churning out low quality docs. The article listed some stats where Apple is not churning out enough docs. So there isn't even quantity
    - lapcat 3y ago
      > What kind of mythical quality is you imagine required to add examples to documentation??? I can see that you have no respect for the difficulty of writing good documentation.
      - 3y ago
eviks 3y ago
Most of the issues you've described have nothing to do with the "mythical man-nonth thinking", so it would indeed be possible to just throw more resources at the problem And the talent pool at the level of a single company is practically infinite unless you indeed introduce artificial constraints like not wanting to pay to tap into that wide pool
- lapcat 3y ago
  > Most of the issues you've described have nothing to do with the "mythical man-nonth thinking" Hence the "Besides..." > And the talent pool at the level of a single company is practically infinite unless you indeed introduce artificial constraints like not wanting to pay to tap into that wide pool I just explained how that's untrue, and it feels like you completely ignored what I said. You can't just say that Apple is "a single company" like any other company. Apple is the largest platform vendor in the world. How many other single companies have platforms like iOS, macOS, watchOS, tvOS, and now VisionOS? How many other single companies have effectively two bespoke programming languages, Swift and Objective-C, much less one? Perhaps only Google and Microsoft are comparable in their massive need for platform docs.
  - eviks 3y ago
    >You can't just say that Apple is "a single company" like any other company. Apple is the largest platform vendor in the world. The world is HUUUUGE (even limiting by language), so not only can I say "a single company", I can raise it to the level of "a single tiny company", especially when it comes to such a small scale issue > How many other single companies have platforms ... bespoke programming languages How does it matter? There are gazillions of educated people in the world with all the skills for a couple of order of magnitudes more languages than just 2! And it's especially preposterous making this arguments after waves of layoffs in the tech sector And you can't reject a simple solution "just pay more" with "companies don't value doc writers": that explains why they don't hire enough people/don't care about the quality of their output, not that there are some inherent talent pool limitations
    - 3y ago