REST doc tools and workflows


#1

A really good conversation about REST docs started over on twitter, but I’d like to continue it here where we have more room. Here’s the storify:

http://sfy.co/f18uq

And here are my initial thoughts:

Andy’s solution is brilliant if you need to keep your docs in synch with your code and if your code is your single source of truth for your (REST) APIs and how they work. I’ve worked with it, and I love it. It’s utterly awesome for keeping writers and programmers (literally) on the same page.

But if you’re starting with design – with your API definition in, say, Swagger – and if that definition is your single source of truth, then you probably need not just a different doc solution, but a different way of thinking about how doc is related to the API design.

Specifically: if you generate a spec/definition from your code and validate it against the initial spec (one ideal workflow, at least), then it might make more sense to keep your doc in synch with the API definition, starting with a tool like Swagger2Markup (yes, I’d prefer the asciidoc flavor :-)), and proceeding to flesh out the content from there.

That said, I’m just beginning with a new team that is planning/hoping to work with this doc-from-spec workflow, so I can’t speak to its success in the real world. I’ll keep y’all posted if you’re interested, though, and I’d love to read any feedback you might have about its potential utility, flaws or gotchas, or anything else.

cheers, Jennifer


#2

We use Doc Pad for our documentation. I wouldn’t say it is ideal, but it works okay. Developers seem to like it, but from a technical writer’s perspective, it is clunky. Technical writers are typically used to using the classic tools in the tech writing industry such as FrameMaker, RoboHelp, wikis, etc. You can just pop in and out of those applications and do what you need to do. Whereas, with DocPad, you have to kickoff builds to see what your content will look like once it is rendered. You often just need to go in and fix punctuation and it takes 2-3 times longer just to see that it rendered properly. Kind of a pain and very time consuming. Maybe this is something specific to our implementation. Does anyone else experience the same?