I definitely agree that a lot of these configuration option docs have outgrown the tables. I do however think the giant table as a reference to lookup configuration property names and default values is handy; I think maybe a system of links in the tables, like "see coordinator balancing docs for more details" or whatever, where the implications of settings could be described in greater detail might be more appropriate than embedding all of the information in the tables. I do like the idea of like nested hidden larger descriptions so you can sort of have both a table and a fly out large description to keep it similar to what we have and not have to update or add documentation in multiple places, but I have no idea how that works in markdown world or if it's possible.
On Tue, Mar 5, 2019 at 3:04 PM Roman Leventov <leventov...@gmail.com> wrote: > On Mon, 4 Mar 2019 at 21:36, Gian Merlino <g...@apache.org> wrote: > > > 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. > > > > Sounds like a good nudge for ourselves to always seek for opportunities to > remove configurations! Besides, we may reorganize the page to show only > configuration names, and then a full description is open (like a "spoiler" > but not exactly, I'm not sure how this HTML control is called. Similar to > how FAQ lists are organized sometimes) when the option name is clicked. > Markdown->HTML converter that we use may support this, so the doc may need > to become a proper HTML page. > > 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. > > > > I'm afraid the necessity to find a place for a section, inner feeling that > a section should be "big enough" to justify its existence, the necessity of > inter-linking in markdown will make it even less likely in practice that > developers will create good docs with comprehensive discussions of > configuration options and their values. >
