Me: code is documentation
Users: we need documentation too
Me: convert code to documentation

Yes!
Documentation is for unreadable code.
Don‘t write unreadable code.

Learning to write readable code made a world of difference for me. The code is way cleaner, smaller functions/methods, and minimal comments needed.

@Lensflare I disagree, documentation is for hard to understand code. It might be very readable but incomprehensible without context.

@BobbyTables smaller isn't better. Locality is better.

Coding is easier than documentation to read and write for me. I can spend ages on writing documentation. Always doubting choice of words / formal / informal / this / that etc. Not consistent in it. Also, think it's hard to assume what a user know do don't know how deep I should go into detail

ye I like developing a coding style that then is faster for me to read than words

actually when I left a company they had an exit interview for me a month later for some reason and during that a manager said the new guy they hired to take over my stuff said my code was amazing. I actually don't write any comments basically

AND EARLIER ON DEVRANT I ASKED HOW OFTEN DOES IT HAPPEN THAT YOU INHERIT A CODEBASE THAT'S NOT A MESS AND I GUESS ITS RARE SO I WIN HAHA

@jestdotty problem with documented code - it requires maintenance. So adding useless functions are harmful

@retoor Break it up into files. I assume you already do this.

Now, split the file into face and guts, meaning is the user supposed to touch this or not. If most of the file is accessible, you're doing it wrong.

And there, you're done. Minimize entry points and in the process eliminate what doesn't require immediate explanation. Work from there.

Best regards,

I the only docs I write are fucking comments.

@atheist you don‘t disagree because with "unreadable" I actually included things like incomprehensible, hard to understand, etc. :)

"unreadable" in its literal sense doesn‘t mean anything because of course you can actually read it. So I‘m using it as an umbrella term for all kinds of wtf code.

@Lensflare touché, I think my problem is the project I'm working on is a data analysis tool, the software engineers don't understand the maths stuff (there's literally a cr comment asking why we do something and my response is just a link to a Wikipedia article) and the data science folks, most of whom are crappy programmers so I've got to put in words what we're doing. I can't win...

@atheist to be fair, some math formulas or algorithms can't be written in a comprehensible way.
That’s one of the rare cases where comments/documentation makes sense.

@Liebranca I prefer one long markdown file. I have some docs in private project, so much edits, markdown shows up on my codes languages graph for a piece. Codeium gives so far nicest statistics than other apps. I reinstalled codeium again

I understand math in code but not on wikipedia

and my math major roommate doesn't understand the math on Wikipedia either so I think all the math people are full of shit

i think a good documentation should surmise the intention of the code without having to pour over hundreds of files.
also, even if the code is clean and easy to understand, you still have to have a minimal grasp of the architecture used and the overall components to navigate a project.
i personally believe a good code is complementary to the documentation, as well as the version management, but they do not substitute.