[mlazos]

My team at work (Microsoft) uses a custom document renderer based on markdown. So to enforce good documentation we have two main safeguards. The first is that we have a static analysis tool that forces everyone to have properly formatted comments on functions/classes/fields or else the code won’t even build. The second is more informal but we have a requirement on our team that every new feature requires a corresponding design doc and that when the feature is checked in the document gets checked in with it. Subsequent changes that change the API are also required to change the design doc in order to pass code review.

[mguijarr]

Thanks for your reply. So even at Microsoft developers have to write documentation themselves ? There are no technical writers to help ? I do not know how to catch up with the documentation now there are tons of undocumented code - your ideas are great for ensuring the situation won't reproduce but I need to catch up too. Thanks.

[mlazos]

So for public facing documentation on an API there are technical writers (like for support docs) but for internal documentation we are expected to keep code well documented. Yeah it might be good to just start having these safeguards and as the code base churns it will gradually get fixed.