What are the diagrams I should made? I'm thinking an overall diagram showing the various applications and services.
UML Component Diagram and Deployment diagrams for this are essential.
We use Argo UML. The price is right. It works well.
And then some sequence diagrams showing the most important or complicated processes.
Only if there is a proven need; i.e., someone asks for it.
About text documents, I'm a bit uncertain about when to put down on paper. Most developers don't like to either write or read long documents.
False. Developers don't like to read rambling, unfocused documents that lack concrete code examples. Hints: Focus. Code.
Another hint.
Avoid fancy desktop word-processing tools. Documentation -- like code -- should be plain text and checked into your code repository.
We use Python-based Sphinx and docutils. The documentation is written in RST (ReStructuredText) markup. Simple tools create HTML pages or LaTeX (and later PDF) from the simple RST source. Diagrams are exported as PNG's so that they're easily processed by other tools.
Since the documentation is plain text, it's easy to write, easy to edit, easy to copy and paste and (above all) under source code control along with everything else.
Another Hint.
To the extent possible, build documentation from the code.
Sphinx can pull comment blocks from the code. Since we use Python, it's trivial to produce a complete, good-looking and well-organized document from the code plus extra RST files.
The "extra" files are the use case overviews (for which no code can possibly convey the information), the architectural overviews, plus management overheads like the backlog, operational guide, administrative notes, etc.
