I'm a bit scared that doing this would make the already large list of configuration options (http://druid.io/docs/latest/configuration/index.html) become even more daunting and difficult to wrap one's head around.
Since, so often, multiple parameters interact with each other, maybe it would make sense for the larger explanatory texts to be written in their own sections, with the parameter tables linking to them? It makes sense with processing buffer size and num threads configs, for example, since they aren't just important alone but they do relate to each other as well. On Mon, Mar 4, 2019 at 4:03 PM Roman Leventov <leven...@apache.org> wrote: > 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. >
