provision: improve docs and fix some golint warnings

At least warnings that are fixable.