Mmmm, we believe papers are not enough to document code. We use a lot REPLs in Lisp and python for that.
Most of the time, this means making things smaller and modularise those. It takes a lot of work and there is always an initial resistance from the team for doing it. But it doesn't take much for them to realise how powerful and useful those interfaces are once they are in place and work.
A paper alone with code is kind of dumb, you need something people can interact with by discovery, by doing, experimenting, just like we do as children with the world surrounding us.
Just having some explanation is not enough: People just don't understand things reading about them, but formulating hypothesis about their understanding and confronting those with reality.
Without them, people are not going to be understanding what you believe they are understanding, but their own idea, that is often totally wrong.
Most of the time, this means making things smaller and modularise those. It takes a lot of work and there is always an initial resistance from the team for doing it. But it doesn't take much for them to realise how powerful and useful those interfaces are once they are in place and work.
A paper alone with code is kind of dumb, you need something people can interact with by discovery, by doing, experimenting, just like we do as children with the world surrounding us.
Just having some explanation is not enough: People just don't understand things reading about them, but formulating hypothesis about their understanding and confronting those with reality.
Without them, people are not going to be understanding what you believe they are understanding, but their own idea, that is often totally wrong.