API documentation

I’m interested in making the API documentation less “mechanical”. I’ve made a first proposition that would help to categorize and/or order the fields of each object of the k8s API, so we could introduce the fields by categories, the required, most important firsts, etc.

We could also unroll some field and its subfields when the depth of this field is not too long, and the field is important.

You can read my proposal here: https://github.com/kubernetes/enhancements/pull/1156

Discussion is welcome