Documentation and writer-reader imbalance

It's not enough that the documentation is short; it must be clear too, written in the most effective way possible. This doesn't necessarily mean to be visually appealing if we'll introduce a mixture of bolds, italics, saturated colors, links, tables and diagrams in one big mishmash. We can still use these elements, but do so judiciously, to save the reader from the numerous switches that can be tiring. It's much better to batch things of the same type where possible, then to alternate different styles. Text, text, text, diagram will read much easier than diagram, text, diagram, table, text with individual words in red italic.