3 ms·

I've done this, 100% tested documentation for a complex project, and it was a nightmare to maintain (eventually abandoned). Maybe it makes sense for simple pro

• chipotle_coyote 8y ago
  It shouldn't be an incredible nightmare as long as your toolchain is set up to handle this. Realm.io's documentation followed the "docs as code" notion of having documentation under revision control[1], but took it a step further -- the docs repo was tested by CircleCI every time you pushed to master, and the tests extracted the Cocoa-based examples and ensured they compiled without error. During the time I was there, they hadn't built an equivalent for the JS and Java examples, but it should certainly have been possible. [1]: "Docs as code" sounds obvious to people at startups, and we did this at RethinkDB and do it where I am now, but it's relatively new to the traditional technical writing world. (I wandered in here from webdev, so it made sense to me right off the bat.)
  • j2kun 8y ago
    The problem was that all the interesting examples had nontrivial state that couldn't be mocked.