What’s Your Go-To Method for Documenting Code?

I really like using Doxygen! It helps create documentation straight from the comments in my code, which is a lifesaver for bigger projects.

There are some great tools like Sphinx that can extract doc-strings and Markdown files to build documentation automatically. You can integrate these with your version control tools, like GitHub, which keeps everything up to date as long as your in-code documentation is current.

Here's my approach: I use an IDE that supports documentation formats like Javadoc or Doxygen. It auto-generates stubs for my methods, so I just fill those in. This way, the IDE offers autocompletion, which makes it easier for others to work with my code. Just be careful with YAML files—they’re tricky to document!

Honestly, I don't bother documenting internal methods much because they often become outdated and misleading. Instead, I focus on documenting how to build the project and the high-level design decisions. Those snapshots are what really matter in the long run.

As a technical writer, I've seen developers use both Doxygen and Sphinx effectively. Generally, the devs handle creating the in-code documentation while tech writers clean it up and manage separate Markdown files. If you can find someone who's studying technical writing, they might collaborate with you for experience.