Problems 1 and 3 I could imagine. I would need to learn how to be a better writer to share a literate program.
As someone experienced in the topic, What's the biggest hurdle when trying to refactor the code?
As someone experienced in the topic, What's the biggest hurdle when trying to refactor the code?
It's simply more work - but that "more work" is vitally important, tedious, and resistant to any kind of automated help.
A slight change in code structure, may require many hundreds of adaptions to the literate document, for example.
[0] https://www.postgraduate.uwa.edu.au/__data/assets/pdf_file/0...
I'm trying to find a way to describe this a bit better than the above. I think the easiest way to think about it, is that in most software projects you have a separate document that is the general architecture of the software. It is rare that you will need or want to refactor the architecture, so you try to keep that somewhat faithful to what the code is doing. In literate software, that high level architecture view is part of how you organize the code.
I'd guess it's updating cross-references in prose and rewriting chapters of documentation which no longer make sense after your refactoring.