+1

I can continue keeping the FAQs into `faq.md`.

Finally, wonder if we should have a special section or file for service
brokers. That is all info needed by service brokers to submit usage, or is
this part of `integration.md`?

Best,

max

On Mon, Oct 5, 2015 at 1:20 PM, Jean-Sebastien Delfino <jsdelfino(a)gmail.com>
wrote:

Hi all,

I've been reviewing the Abacus docs, and we currently only have the
following:
- 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:

README
how to get started, build, deploy and run a demo, setup your dev env to
contribute

then under docs/:

api.md
overview and reference doc for our REST API

faq.md
the FAQ that is currently in the README (as that README is getting long),
plus a few more recent questions

config.md
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

integration.md
for integrators of Abacus, describe how to customize the provisioning and
account/pricing services

app-usage.md
describe how we meter CF app usage and process it in Abacus

security.md
describe how to authenticate when calling Abacus APIs, and the CF Oauth
scopes we use for authorization

debug.md
tips on how to debug, trace, instrument the code

design.md
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?

Thoughts?

-- Jean-Sebastien

--
max
http://maximilien.org
http://blog.maximilien.com