In my opinion the best way is to include annotations with the documentation inside the workspace itself. For larger chunks of text you can place an annotation inside a bookmark and then collapse it. This way all the documentation is kept right by the workspace itself, no risk of it getting lost or forgotten in an update. Combine that with some standards (company-wide if applicable) on bookmark use and workspace layout and you end up with a well-designed workspace that can easily be edited by somebody else.

There's a workspace template by @lars_de_vries that should give you some inspiration on how to set this up. You don't have to follow all of that of course, can still implement your own ideas, but it does pay to think about it.

Thanks @redgeographics and @lars_de_vries. I like the workspace template and the ideas it gets across.