3 ms·

I'd settle for properly written documentation. I'm a long time AWS customer and I love AWS, but to be honest, the documentation is bad. I don't think they und

• ravenstine 8y ago
  I find that the structure of their documentation could use some work, but the actual language to be fairly good. And by good, I mean less bad when contrasted with most documentation. To go off on a bit of a tangent, I'd prefer that documentation be split up into two parallel versions that are heavily linked but mostly separate: - Code examples describing everyday usage - Detailed API/system descriptions AWS should do a better job on the former, although that'd be a massive amount of work for them at this point with little payoff. I find that I end up relying much more on Stack Overflow and even code from wrapper libraries to understand how to do relatively uncomplicated things with their API. In general, however, I'd prefer it that all documentation be more the former than the latter. I find that when I'm given everyday examples, that aren't hideously formatted on the webpage, I can get a better understanding much quicker and become far more productive. Most documentation isn't good at either providing practical examples or actually explaining usage. I feel like there's a missing link between English-majors and software engineering; if there are English-majors who also understand programming, they should be paid handsomely to write documentation. But when do we ever see job postings for specialists in writing documentation? I've never seen such a job title.