Show a lot of examples.

Writing proper documentation is an iterative process. We usually use the following pattern at IBM:

Preparation and Writing a first Draft

Comment your code extensively, explain especially public facing functions very detailed. Explain parameter and types.
Then wait some days, extract the comments and use the extracted comments to write documentation. Try to not look too much at the code during this step, in order to avoid getting lost in details.

Proof Reading

1. Get somebody on board for proofreading and checking, if the documentation is comprehensive and whether other people who don't know about the code, can follow along
2. Write down any questions that came up by this person. Try to answer the questions within your documentation, try to avoid adding extra subsections, that only answer these questions in specific. Instead try to add information to your documentation, that clarifies the questions
   • To also answer related questions, keep the added information as general as possible!
3. (optional) Get another person on board
   • Repeat the Proof Reading steps with this person
4. Repeat the Proof Reading process with these persons

You can repeat the process until you find your documentation in a mature state. Dragging in more people ensures that the documentation not written in a way that is tailored to one specific reader. Each new pair of eyes gives you a new perspective on what is missing, wrong or difficult to understand.

Just my two cents on comments (not necessarily helping you with how to document). Comments are a good thing, but only when used with discretion. I would resort to writing comments only when I think that my function is not able to convey its intents via its name, arguments and return type. Or when there are complex business logic that cannot be understood easily. Even in that case I would rely on my unit tests to serve as a documentation for my method.

I wrote an article on that topic: medium.freecodecamp.org/the-truth-...

The first step is to decide what kind of documentation you need. Who is the audience? Will it be primarily used by developers (like yourself) who need to get familiar with the code base? Or is it geared towards users who just need to get things done and don't particularly care about the implementation. Both types of documentation are very important, but they are written very differently.

Once you have an audience in mind, start with an existing tool like Doxygen or ReadTheDocs or whatever tools are being used by codes similar to yours. Doxygen is particularly helpful for developer documentation because it can automatically create caller/callee diagrams for your code base. This is immediately useful to everyone on the team. With some skeleton documentation in place, work on getting buy-in from the rest of the development team.

Once everyone agrees that documentation is important, make it a part of the development cycle, not something that happens later. Require that pull requests for new features include the documentation. Or, enforce a commenting style that can be parsed by tool (e.g., Doxygen) and add this as a requirement. Every time someone refactors old code, they can add a small piece of documentation.

It's a slow process, but definitely worth the time! I highly recommend that a documentation piece become a requirement in all pull requests to help keep any existing documentation up-to-date.