Write a complete assertions guide

[joel-costigliola]

Users are often not aware of useful assertions, a guide showing best practice assertions would help a lot.

[joel-costigliola]

Reusing some part of http://www.baeldung.com/introduction-to-assertj would be a good idea.
Reuse the release notes examples.

[joel-costigliola]

Add an Android section to address #54.

[joel-costigliola]

http://www.baeldung.com/assertJ-java-8-features

[filiphr]

What are your plans for the guide? Do you plan to keep the same format as you have on the website currently?

Have you considered using Asciidoc with Asciidoctor. It is really similar to markdown and you can also include code snippets from tests which means that once a test is updated the documentation is updated as well 😄 . It is widely used in open source projects. For example Spring, Spring Boot, Hibernate, Vavr, MapStruct, and many more have moved their entire documentation into it. It creates HTML and it can create single HTML or multiple pages you can configure it.

If you decide to go for it, I would suggest you to have this asciidoc files in each project and it will be maintained as part of their release cycles, you then can include it into the website once you publish a release. If they are next to the projects it would be easier to maintain and you can include snippets from the tests into it.

[joel-costigliola]

I need to have a deeper look at it but that seems a really good idea.

[joel-costigliola]

started but a bit busy, check: https://assertj.github.io/doc/
PR would be awesome (in https://github.com/assertj/doc)