Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DDOC-4: added two new beginner docs and refreshed another #6756

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

claytonfinney
Copy link
Contributor

Cleaning up some docs and staging some to be put on docs.2600hz.com :)

Part of an initiative to revamp our documentation experience. PRs merged for this purpose are short-term, since docs are still built from the KAZOO monorepo.


## How do I Get Started?

KAZOO is open-core, meaning that you are free to clone, modify, or otherwise utilize the [kazoo-core](https://www.github.com/2600hz/kazoo-core) source code. If you’re interested in building KAZOO from source, this [guide](https://github.com/2600hz/kazoo/blob/master/doc/installation.md) is an appropriate jump-off point. Otherwise, visit our [website](http://2600hz.com) to get in contact about scheduling a demo.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Open core" has nothing to do with the kazoo-core repo, for the record.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also links should be to the docs site version of the installation guide and not the repo, right?


KAZOO is open-core, meaning that you are free to clone, modify, or otherwise utilize the [kazoo-core](https://www.github.com/2600hz/kazoo-core) source code. If you’re interested in building KAZOO from source, this [guide](https://github.com/2600hz/kazoo/blob/master/doc/installation.md) is an appropriate jump-off point. Otherwise, visit our [website](http://2600hz.com) to get in contact about scheduling a demo.

We at 2600Hz also offer production-grade applications as well as KAZOO cluster hosting and management as services. Visit our [website](http://2600hz.com) for more information. All our guides will assume that you have a KAZOO environment to develop against, whether you’re an open source user or a 2600Hz customer.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https only links please


Almost all requests and responses to the KAZOO API are serialized using JSON, unless otherwise specified in the documentation. You may find, for example, an endpoint will respond with XML instead of JSON.

The KAZOO API is built on widely-adopted architectures and specifications such as REST (for API consistency) or [JSON-Schema](http://json-schema.org/) (for data validation). You can use any HTTP client to interact with the API, whether via a programming language’s HTTP library, a HTTP GUI like Postman, or just plain old cURL in the terminal. There is very little overhead in order to get started making requests against your KAZOO account.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The disrespect on cURL's name with "just plain old"...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention was that cURL is the "barebones" approach! I can change it to "ol' reliable" if you'd like ;)


## KAZOO Versioning and API Consistency

Expect to encounter inconsistencies with official documentation material if you are using features or KAZOO versions that are outside of what we use in our own stable commercial environments. This means that, if you are for example running an older (or newer experimental) version of KAZOO, that this documentation may not be accurate for your given environment. We recommend using our [community forums](https://forums.2600hz.com/forums/) to ask questions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Second sentence is awkwardly constructed

**index.html**

```html
<head>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume it might be helpful to package the snippets in this doc into a complete HTML/JS/CSS/whatever set of files so folks can download them to modify at their leisure?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Somewhere like doc/user_guides/code_examples/ ?


Since pagination can be turned off by a client-supplied query string parameter, it is important that KAZOO still protect itself from overly large datasets being loaded. Examples seen include large CDR listings, call recording listings, and ledger listings.
1. `/{RESOURCE}/{RESOURCE_ID}`
- A resource, such as `devices`, `users`, `callflows`, et cetera.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So you should probably not use resource here as in KAZOO a resource represents upstream carrier configs.

We generically call them collection and entity, so accounts is the collection, {ACCOUNT_ID} is the entity.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants