[abacus] Topics for Abacus docs?
I've been reviewing the Abacus docs, and we currently only have the
- a README describing how to get started with the code, build, run a demo,
set up for developing an Abacus module and the beginning of a FAQ;
- a doc of some of our REST API showing the URL, methods, return codes,
sample JSON bodies and JSON schemas.
The project is growing and I'm thinking that it's probably time to start
adding more and better documentation to help our users.
Here are a few topics I thought we should cover, and a straw man proposal
for how to structure these docs, for discussion:
how to get started, build, deploy and run a demo, setup your dev env to
then under docs/:
overview and reference doc for our REST API
the FAQ that is currently in the README (as that README is getting long),
plus a few more recent questions
for service and runtime providers, overview of how to configure Abacus for
metering your own resource types, define your metrics, metering and
aggregation calculation functions etc
for integrators of Abacus, describe how to customize the provisioning and
describe how we meter CF app usage and process it in Abacus
describe how to authenticate when calling Abacus APIs, and the CF Oauth
scopes we use for authorization
tips on how to debug, trace, instrument the code
design notes, in particular describe the life of a usage doc as it flows
through Abacus and usage gets metered, accumulated, aggregated etc,
also, a description of what we store in our databases
I'm probably missing a number of important topics but does the structure at
least make sense?
What else would you guys like to see added -- or add yourself, pull
requests welcome -:) to these docs?