I think it's when you try to separate code and documentation that things tend to get out of sync quite easily. For example; we have a settings system; all keys

I think it's when you try to separate code and documentation that things tend to get out of sync quite easily. For example; we have a settings system; all keys are defined as constants in code and they have attributes that clearly describe every aspect which is the used to generate the documentation. If you add a new settings, you instantly write the documentation for it as well; so far, it has worked great and I think this could/should work for other parts of the code as well.