How to document services

A service description for customers should try to answer the following FAQ:

  • What is the purpose of the service? What is its value for me?
  • What are limitations/restrictions/requirements/assumptions of the service?
  • Is there an example of another public project I can follow?
  • Is there an API? API Explorer link? How do I authenticate?
  • Can my internal project use the service? Does it implement ACLs?
  • Where is the documentation?
  • Where is the design doc?
  • How do I enable the service for my project? If by adding a config file to the project repo, what is the name of the config file and where is the documented .proto?
  • How do I provide feedback? How do I file bug for the service? What is the crbug label?
  • Who do I contact to if I have more questions?
  • Does it have SLA?

See Hello World Service as an example.