I like the idea of a `provider.md` and even maybe `on-boarding.md` that
will eventually point to our self-on-boarding process.

Best,

max

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

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

Thanks!

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`?

integration.md was more about how you'd customize Abacus to fit in your
particular Cloud platform / CF deployment,
config.md for service/runtime providers to know what to do to get their
(service/runtime) resource types on board Abacus,
api.md for how to use the api to submit usage and get usage reports.

Maybe we need a paragraph somewhere to say something like 'if you're a
service provider, first tell us what resources you want metered (and go to
config.md for that on boarding step), then once that's done use our
resource usage API to submit your usage (and that's in api.md).

We could also have a provider.md doc with 'everything you wanted to know
as a service provider'. That may be a better organization...
Not sure until we get more input from service providers or integrators on
what they're looking for.

-- Jean-Sebastien


On Mon, Oct 5, 2015 at 1:28 PM, Michael Maximilien <mmaximilien(a)gmail.com>
wrote:

+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

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