Rows in tables in markdown must fit a single line (unless you use full-blown HTML <table><tr><td> syntax), including the configuration option descriptions. Descriptions should properly be large, sometimes even multi-paragraph texts with a discussion of how the parameter should be used, how lowering and increasing the value affects the system, etc. Instead, currently many configuration option descriptions in Druid consist of a single sentence that doesn't explain much, if anything, beyond the configuration option's name itself.
Instead, I suggest that configuration options are titled sections in the documentation each on its own, for example: ### `druid.coordinator.someAwesomeOption` Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. *Default value:* `false` *Required:* no ### `druid.coordinator.nextAwesomeOption` ... https://github.com/apache/incubator-druid/issues/4861 would fix this problem too.
