4 ms·

> First, the yearly OS release schedule, which began in 2012 on the Mac, didn't leave enough time to write documentation. I'd think this problem could be partl

> First, the yearly OS release schedule, which began in 2012 on the Mac, didn't leave enough time to write documentation. I'd think this problem could be partly solved with money, i.e. hiring more writers. Even if the docs had to lag the OS release by a few months, I still suspect the fundamental reason is: > Third, Tim Cook and Craig Federighi just don't give a crap about quality.

lapcat 3y ago
> I'd think this problem could be partly solved with money, i.e. hiring more writers. That's classic Mythical Man-Month thinking.
- russelg 3y ago
  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.
- CoastalCoder 3y ago
  > That's classic Mythical Man-Month thinking. I see why you said that, but I don't think that's the case here. The tech writers don't necessarily need to collaborate with the developers as the software is being developed. E.g., the tech writers might be able to look at new APIs, the source for for their implementations, and any in-house code that uses / tests those APIs. And then write documentation based on what they find. If they're able to talk to the developers during or after the API is released, all the better. Disclaimer: I'm not a tech writer. I'm just speculating on how this could be made to work.
- Dylan16807 3y ago
  I don't see how. That applies to trying to get a specific project done faster, when it's already pretty far along in the development cycle. The problem of an area not getting enough attention for years is a great opportunity for more workers.

lapcat 3y ago

> I'd think this problem could be partly solved with money, i.e. hiring more writers. That's classic Mythical Man-Month thinking.

russelg 3y ago
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.
CoastalCoder 3y ago
> That's classic Mythical Man-Month thinking. I see why you said that, but I don't think that's the case here. The tech writers don't necessarily need to collaborate with the developers as the software is being developed. E.g., the tech writers might be able to look at new APIs, the source for for their implementations, and any in-house code that uses / tests those APIs. And then write documentation based on what they find. If they're able to talk to the developers during or after the API is released, all the better. Disclaimer: I'm not a tech writer. I'm just speculating on how this could be made to work.
Dylan16807 3y ago
I don't see how. That applies to trying to get a specific project done faster, when it's already pretty far along in the development cycle. The problem of an area not getting enough attention for years is a great opportunity for more workers.