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.
I interned at NASA, working on statistical modeling and machine learning projects. Now I'm at Ferguson Enterprise, working on applying UX principles to internal tooling!
Now that I think about it our audience is mainly other developers. We have a BA that does documentation for the user.
Right now I got the team to review our documentation during code reviews, which forces us to do it during major code changes. But you are right, it should be done more frequently (maybe every commit), so it doesn't feel so much like a burden. thanks!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
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.
Now that I think about it our audience is mainly other developers. We have a BA that does documentation for the user.
Right now I got the team to review our documentation during code reviews, which forces us to do it during major code changes. But you are right, it should be done more frequently (maybe every commit), so it doesn't feel so much like a burden. thanks!