I've created an issue about this problem: https://github.com/apache/incubator-druid/issues/7210
On Tue, 5 Mar 2019 at 20:36, Eyal Yurman <eyurma...@verizonmedia.com.invalid> wrote: > Just for comparison, this looks nice, isn't it? > https://spark.apache.org/docs/latest/configuration.html > Original .md: > https://github.com/apache/spark/blob/master/docs/configuration.md > > On Tue, Mar 5, 2019 at 3:20 PM Clint Wylie <clint.wy...@imply.io> wrote: > > > 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. > > > > > >
