When you look at our directive docs, the parameters listed in the table are in random order. It is preferable to have required parameters first, and optional ones after them.

Possible solutions:
a) implement automatic sorting according to "required" column (this could maybe be done using CSS, toghether with #260)
b) keep the same order as defined in directive documentation (manually keeping the options in desirable order is I think a reasonable trade-off). That means the parameters object would have to changed from a dict to a list.