HN Explorer

3 comments

[ 0.22 ms ] story [ 21.2 ms ] thread
joshcanhelp
This looks great so far and glad to see others tackling this tough problem! I've spent a lot of my time writing documentation and example code and, while I love the process, it's very hard to keep it all up-to-date. I wrote up a spike I tried a while back that worked well for what I needed it for:

https://www.joshcanhelp.com/testable-documentation-spike-1/

NyuB
I also find your introductory post to the subject (https://www.joshcanhelp.com/testable-documentation-intro/) really neat !

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).

joshcanhelp
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.