  Automatic Static Analysis Tools (ASATs) are widely used by software
developers to diffuse and enforce coding practices. Yet, we know little about
the documentation of ASATs, despite it being critical to learn about the coding
practices in the first place. We shed light on this through several
contributions. First, we analyze the documentation of more than 100 rules of 16
ASATs for multiple programming languages, and distill a taxonomy of the
purposes of the documentation-What triggers a rule; Why it is important; and
how to Fix an issue-and its types of contents. Then, we conduct a survey to
assess the effectiveness of the documentation in terms of its goals and types
of content. We highlight opportunities for improvement in ASAT documentation.
In particular, we find that the Why purpose is missing in half of the rules we
survey; moreover, when the Why is present, it is more likely to have quality
issues than the What and the Fix.
