Add/decide on top level sections

[munnerz]

We should decide on the top level sections for the docs.

From brief discussion on Slack:

• Concepts - describing the various different concepts in controller design

  • level based programming
  • an overview of the various core functions client-go provides
  • a 'map' of client-go, apimachinery, api, code-generator, restclient vs typed client so users understand what is what
  • details on the 'tools' in client-go (i.e. leader election, informers maybe? - this may link out to examples)
  • details on what code-generator does, what each generator is used for, how it works, why it exists

• Tutorials

  • building a project from scratch
  • generating reference API documentation
  • generating openapi validation schema
  • adding leader election to your controller

• Contributing

  • how to contribute to these docs

/cc @sttts @LiliC @nikhita

[nikhita]

From @sttts on slack: http://using-client-go.cloudnative.sh/ by @mhausenblas.

It is a good place to start. :+1:

[xmudrii]

Potentially good topic could be 'Testing and mocking with client-go', describing how to write unit tests for controllers/API servers, how to create and manage resources from tests, how to mock indexers..

'Vendoring client-go with dep/GoDeps/Glide' may be a good article as well. That one could also cover vendoring code-generators (for dep, this can be useful https://github.com/golang/dep/issues/1306#issuecomment-384678415. Running in a Docker container is an option as well).