Instead of embedding code in markdown, I actually generate the markdown from code. Which with Kotlin is easy because you can write your own DSLs. And I get to refactor my code and documentation at the same time. It has some other nifty features like capturing output that you can show in the Markdown and a few other things.
If you want to see it in action, check out the documentation for my kt-search project. There are probably a lot of other libraries out there that do similar things. But it's a thing that most projects don't seem to rely on for their documentation. And breaking code samples are a major hurdle for writing documentation to begin with.
I find that addressing that gets you in a mode where you are documenting things by default. And good documentation also reveals design flaws because you are kind of forced to eat your own dog food by writing working code that shows how you would use a particular feature. I'm basically constantly trying to make life easier for both myself and my users.
Instead of embedding code in markdown, I actually generate the markdown from code. Which with Kotlin is easy because you can write your own DSLs. And I get to refactor my code and documentation at the same time. It has some other nifty features like capturing output that you can show in the Markdown and a few other things.
If you want to see it in action, check out the documentation for my kt-search project. There are probably a lot of other libraries out there that do similar things. But it's a thing that most projects don't seem to rely on for their documentation. And breaking code samples are a major hurdle for writing documentation to begin with.
I find that addressing that gets you in a mode where you are documenting things by default. And good documentation also reveals design flaws because you are kind of forced to eat your own dog food by writing working code that shows how you would use a particular feature. I'm basically constantly trying to make life easier for both myself and my users.