[abacus] Topics for Abacus docs?

Jean-Sebastien Delfino

Hi all,

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
account/pricing services

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?


-- Jean-Sebastien

Join {cf-dev@lists.cloudfoundry.org to automatically receive all group messages.