For a nicely documented and clean Matrix client implementation in Python, see weechat-matrix[1] and the matrix-nio[2] library it's based on. There's also Mirage[3] which is also based on matrix-nio and is a GUI client.

[1]: https://github.com/poljar/weechat-matrix

[2]: https://github.com/poljar/matrix-nio

[3]: https://github.com/mirukana/mirage

Last I tried to read the spec (months? a couple of years? who can even remember these days), it kind of sucked. The allegedly separate server spec silently presumed knowledge of all of the client spec without any specific references, and the description of the merge strategy was organized as a sequence of forward(!) diffs of successive algorithm versions. I gave up.

Has it improved since?

The spec is ok, but you do have to bounce around a lot. There are still areas that need improvement for sure, but we’ve been using it for about a year now with some level of success in building a chat product.

What are you building? I am about to start on a similar project.

Matrix powers our live chat product at https://groovehq.com