>I’ve been through this documentation story before. I can predict how it ends. By the time you read the documentation it’s out of sync with the code so you end up reading the code anyway. But then you feel bad, so you write more documentation & force yourself to update documentation whenever the code changes. But that takes time away from development & the pressure is on, so you stop writing/updating.
The story doesn't always end this way.
There are two types of documentation:
* Those that don't really go out of sync when you update the app - e.g. intros, overviews, contribution guidelines, justifications, etc.
* Those that can go out of date when you change the code - API references, how to guides, tutorials.
If the latter is autogenerated from tests + test metadata (how-to guides/tutorials) or from code (API references), it won't go out of date.
With termux I can then hit a button to run a script and it will instantly generate a pretty PDF using latex from an orgzly note and fire off an android share intent.
The nice thing about this set up was that if a recruiter called me while I was out and wanted a CV quickly with a couple of tweaks made I could just do it on my note taking app and email an updated PDF in a few seconds.
In theory I could easily change the style of the CV but in practice I haven't felt the need to touch it in years.
I used to be really good at working with big balls of mud.
I actually even started enjoying it at some point - it felt like a mixture between a crossword puzzle and archaeology. There was also something nice about being good at something other people hated that was nonetheless very critical.
Somewhat ironically though, the better I got at it, the class of job I got the better the quality of the code I ended up working with.
Now my mud wrestling skills have atrophied a fair bit.
Generally speaking, mud wrestling jobs exist in traditional IT departments, not tech product companies, and the jobs pay far less than those where the code is the product. For better or for worse, but the existence of "big balls of mud" is largely a result of "you get what you pay for" mentalities in non-technical CIOs & CTOs... or industries where IT spend is below some low threshold (e.g. 1% revenue).
I really think that archaeology you speak of is great for building skills, and as a result when giving the opportunity you start building much more elegant solutions.
My career path has followed a similar trajectory but I do enjoy a good "mud wrestle" as you call it every now and then :)
It works for user facing documentation too. There are actually pretty good reasons for this - e.g. you can use the test to autogenerate up to date screenshots with playwright to put in the documentation.
I'm pretty convinced that there should be a single source of truth for specifications, tests and documentation but I think the industry will take a while to catch up to this idea.
I built a testing library centered around this (same as my username) but it's hard to get people to stop writing unit tests :)
Really it comes down to the team you are working with. If you have user-facing documentation authors who are happy with Markdown and Git you can probably get this to work.
I think screenshotting needs to be integrated into the tests though - if a scenario involves a wizard or something, the latter screenshots will be dependent upon the actions in earlier steps.
It records a video while running the test and then at the end runs it through FFMPEG to make a smaller, slowed down GIF that can be embedded in the autogenerated docs.
It's quite rudimentary though. I've been meaning to try making something more sophisticated and even potentially do additional automated video editing to inject text from the steps or something.
I created a command line app for applying jinja2 to orgmode. I did it to scratch the itch of being able to generate pretty latex PDFs for my CV and for printed letters with content from my note taking app on my phone.
I published it on pypi/github out of habit, but it's primarily about scratching my itch and I doubt anybody except me will really use it. There's some interest in doing this type of thing with org mode but it all centers around LISP and emacs (neither of which I like).
I wrote an integration testing framework which I wanted to integrate with a tool exactly like this so it could be used to, e.g. test a command line app like vim.
Expect is what I tried to integrate with first. It falls over quite quickly with any kind of app that does anything mildly complicated with the terminal.
Interesting. When we decided to build ht we didn't compare it to expect (which I hadn't heard of or used) but I'm comparing the two now as they seem related.
How exactly did `expect` fall over?
From what I can tell, expect does not provide the functionality of a stateful terminal server/client under the hood for you so it isn't as easy to grab "text" screenshots of a Terminal User Interface, which is one of the main motivations behind ht (will update the readme to make this main use-case more clear)
Screenshots was one thing that didnt work that I needed but I think lots of control characters used by command line apps also messed up pexpect.
I built my own probably not very good equivalent of your thing called icommandlib. I'm going to investigate ripping it out and replacing it with your tool.
I built a testing and documentation framework to solve precisely this problem (google for my username to find it).
You write the StrictYAML based tests structured according to your domain language/interactions and then you write one class that interprets them to execute the test and one template file that you apply to generate the markdown/HTML/whatever docs (with test artifacts like screenshots if you want them).
How to documentation then becomes a build artefact that, since it is generated from a test, never goes out of date by definition.
I usually combine this kind of docs with other types (e.g. explanatory) which can't be generated but also dont tend to go out of date.
The "busy work" of low level unit tests is perfectly valid, but TDD still works extremely well with high level integration tests so I don't think a similar criticism necessarily applies.
The story doesn't always end this way.
There are two types of documentation:
* Those that don't really go out of sync when you update the app - e.g. intros, overviews, contribution guidelines, justifications, etc.
* Those that can go out of date when you change the code - API references, how to guides, tutorials.
If the latter is autogenerated from tests + test metadata (how-to guides/tutorials) or from code (API references), it won't go out of date.