I've been in the technical writing field for over 30 years, mostly working on API documentation. My criteria for good API documentation are simple:
Is it accurate?
Is it complete?
Is it necessary?
Accuracy is paramount. If you incorrectly describe an argument as a 64-bit integer, but it's actually a 32-bit integer, you lose your audience.
Completeness is crucial. I hate it when I read an API doc and they fail to give me details of possible error/exception conditions. So this takes a string? How many chars? Min? Max? Does case count? Unicode?
Don't litter a technical doc with sales/marketing blather. I don't care if it's the greatest thing since bottled beer, let me decide. Keep the conceptual stuff in a separate section, as if I care. Don't make me wade through a bunch of new terms you heard on a TED talk. Use industry-standard terminology.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I've been in the technical writing field for over 30 years, mostly working on API documentation. My criteria for good API documentation are simple:
Accuracy is paramount. If you incorrectly describe an argument as a 64-bit integer, but it's actually a 32-bit integer, you lose your audience.
Completeness is crucial. I hate it when I read an API doc and they fail to give me details of possible error/exception conditions. So this takes a string? How many chars? Min? Max? Does case count? Unicode?
Don't litter a technical doc with sales/marketing blather. I don't care if it's the greatest thing since bottled beer, let me decide. Keep the conceptual stuff in a separate section, as if I care. Don't make me wade through a bunch of new terms you heard on a TED talk. Use industry-standard terminology.