Should we mention that this requires root access?

For sure. Any idea where folks got the idea they didn't need root though?

I mean why would you need root for a directory that you'd expect to be owned by root?

I think you still need root to clone the plugin in the first place.

Not necessarily. You could clone it if you run plugn install as the dokku user. However plugn trigger install will fail with the reported error.

root@dokku:/var/lib/dokku# ls -lad ./*/{available,enabled}
drwxr-xr-x 21 dokku dokku 4096 Sep 19 00:27 ./core-plugins/available
drwxr-xr-x  2 dokku dokku 4096 Sep 19 00:27 ./core-plugins/enabled
drwxr-xr-x  2 dokku dokku 4096 Sep 22 16:01 ./plugins/available
drwxr-xr-x  2 dokku dokku 4096 Sep 22 16:01 ./plugins/enabled

EDIT: We no longer sudo -u dokku for plugin:*install* so we can do root things like apt-get.
https://github.com/progrium/dokku/blob/f8c9d9b8239cf5b20020366ecec2e2c799185718/dokku#L44-L47

Interesting, my dokku dir is owned by root...

/var/lib/dokku is owned by root. However we don't install plugins in that directory anymore.

Basically I think this comment outside of the codeblock should be inside the codeblock and we should have sudo prefix on the command. Something like this:

# This command requires `root` permissions as the `install` and `install-dependencies`
# plugin triggers may utilize commands such as `apt-get`. For non-core plugins, please
# inspect those plugins before running the following command as `root` user.
sudo plugin:install <git_url>

# previous versions (0.3.x and below) of dokku require a manual process to install plugins
cd /var/lib/dokku/plugins/available
sudo git clone <git url>
sudo dokku plugin:install

Does that make sense? Keeping the root notes outside of the codeblock is an easy way for users to get confused and complain that the docs are bad because they can't read ;)