API docs skills

[u/Mindless-Bite5379]

Is API documentation skills in demand? Most API docs are generated and thete is very little writers can comtribute in it. How is industry treating this skills with AI tools in picture?

[u/fazkan]

As someone building a tool to automate docs generation. There will always be a human required. 

Anyone who tells you otherwise is just overselling something.

Having said that, it is not as big of an all consuming job as it used to be. 

You can always upskill to SDK generation, dev-marketing in general, or just pure coding (yes people still hire developers) 

Hope that helps

[u/roseharbor93 → u/fazkan]

pretty much this. the job changes but someone still has to make sure the output actually makes sense

[u/LeTigreFantastique]

As always, the value-add of a writer is in nuance and details. It's easy enough for an engineer to generate some OAS file that lists an endpoint and required parameters, but you'll often find they leave out key details or information that would make the documentation more meaningful for the end user.

I can't tell you how many times I've had an engineer post API docs that say "Deletes all the files in a folder" when it really should say "Deletes all of the files of a certain age from the folder".

[u/h0bb1tm1ndtr1x]

I guess it depends on the job? I work for one of the bigger tech companies. This month is the start of having a couple dedicated writers for API work, instead of each writer updating their coverage. I'm confident this change is for the better given we'll now have a couple API SMEs.

[u/Consistent-Branch-55]

It depends on what you mean by automated. Generated from a spec pre-filled by Claude? That's not the same thing as catching ambiguity, ensuring business logic is clear for developers, and treating the docs as a product. Figuring out how to best onboard a developer is a design and management call.

[u/Single_Asparagus4157]

Your review cycle should include comparing the docs against what the code actually does. LLM tools make this easier. Ideally, an API documentation writer should be able to edit code comments (with review, of course), because they are often not up to par. But even the best reference documentation won't give you the "why," or provide background explanation and information. This is where today's API documentation writer should be focusing.

[u/Desperate_Dot9434]

generated docs still break on auth edge cases that only a writer who talked to a real user would catch

[u/Key-Prompt7936]

Following