improve documentation

fixes #1391

and add improvements/fixes to documentation
Sometimes you put `output_file`/`server` almost at the end of the script, sometimes in the first lines... It would be nice to have a consistent location across all the examples...