update docs around generating clients

fixes #138 #136 

@ckarlof r?