The docco spike is quite cool, sounds a bit like inlined Javadoc on steroid to me, as you mention in your final thoughts it could look great for direct source code documentation. Not sure about the immediate readability with all these comments though, I think there is a hard balance to find between wanting documented code/samples and not wating documentation concerns to 'invade' your codebase too much (something you kinda pointed out too).
I totally agree. This would not work well with a large body of documentation and has some big limitations in terms of formatting.
I never got to my second spike but I was looking at maintaining separate code files that could be included and tested atomically. That model was based on how we were trying to do it at a previous position using Contentful for the content management and then pointing code samples to publicly-available files.
The docco spike is quite cool, sounds a bit like inlined Javadoc on steroid to me, as you mention in your final thoughts it could look great for direct source code documentation. Not sure about the immediate readability with all these comments though, I think there is a hard balance to find between wanting documented code/samples and not wating documentation concerns to 'invade' your codebase too much (something you kinda pointed out too).