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. > > >
