Architecture and Design
The primary reason of having an Architecture and Design is to guide the development. It is the code that matters at the end of the day and the way how it is deployed. The Architecture and Design section should provide introduction to the midPoint internals, describing how it is structured and how it works. The important goal of the architectural documentation is also description why midPoint looks like this, what options have been considered and why was the current approach chosen. It also provides high-level overview of the implementation.
However, the architectural documentation should not go deep into implementation description. Such a description will quickly get out of sync with the code and is a terrible burden to maintain. We rather focus on keeping the code itself readable and well commented (see below).
The Code is the Best Documentation
The code itself is the best documentation. The documentation that won't get out of sync with reality. Therefore the first and foremost documentation principle is to keep the code readable. See Java Design and Coding for more details.
Comments in the Code
The implementation that is not obvious from the code should be documented in the code comments. The comments should not describe what is obvious from the code, But the text should describe why it is implemented the way it is implemented. Also point out important details that are not obvious from the code.
Also use Javadoc a lot. It is almost mandatory of all interfaces and strongly encouraged for all non-trivial methods. Good practice is to start writing a method by writing a short Javadoc description and only then write the code.
The Documentation is focused on IDM engineers deploying midPoint. Deployment documentation should contain installation guides, deployment best practices, configuration reference, documentation of known deployment and engineering issues, etc. The overall style and language of the documentation must focus on field engineers, not developers. The goal is deployment efficiency.
is here: Administration and Configuration Guide. Do not forget to update it if you add or change functionality.