lightblue-platform/lightblue-docs-user

User guide for lightblue.

lightblue-docs-user's Issues

Break chapters up into more details

For example, to find details about a specific metadata api I have to scan through all api's to find it:

http://docs.lightblue.io/rest_specification/metadata.html

Gitbooks allow for more levels of hierarchy in chapters. I used them recently for audit hook docs:

http://docs.lightblue.io/cookbook/audit_hook.html

Things that I think should be broken up:

• All the rest specifications
• Possibly any major sections of the language specs. For example, query could be broken into query, projection, sort, update.

Better define what an error "context" is

Exert from user doc:

context: A string delimited with "/" characters that define the context of execution where the error occurred, similar to a stack trace.

This definition leaves me struggling to understand what the context is intended to be. I don't know if it is the recursive use of the word "context" or the comparison to a stacktrace, but regardless, I don't think the definition clearly encapsulates the concept that the context is intended to represent.

For example, why would a context trace be preferred over a stacktrace for a server side error? Or maybe better, what can the context provide that could not be included in an Exception's message? A stracktrace does an excellent job showing where in the code something broke, why duplicate that? That said, a stacktrace does not give any indication of the conditions that caused the exception to be thrown (again, possibly outside of the Exception's message), which is where I think the context does a better job.

I think if we had a clear definition of "context" we could begin to look at the code and ask if various uses of context and/or exceptions are appropriate, or would the other be better?

Create quick start docs

From a sample entity and sample data point of view. A simple entity like country is probably a good candidate.

• how to create new entity (initial fields: name, iso2Code, iso3Code)
• how to update to new version (add field: defaultLocal ?)
• how to create data
• how to query for data

Minor: Using Double quotes marks in JSON

Sometimes (for example in http://jewzaam.gitbooks.io/lightblue-user-guide/language_specification/metadata.html ) the examples/snippet are using double quotes mark for JSON but sometimes it is missing it. I think it would be better to always use it.

Add docs on new 'matches' constraint

New constraint 'matches' was just merged (thanks @skavanagh!) lightblue-platform/lightblue-core#109 and we need some documentation added about it.

Document associations

There's a doc that describes the algorithm for associations already but:

1. it needs moved here
2. additional documentation on how to use associations needs added
3. add docs why it isn't called 'join'

For the third point, some things to consider:

• joins in RDBMS are tight couplings, enforceable with RI (foreign keys)
• lightblue associations are loose couplings, you can associate anything to anything else with any query you would like to try with no restrictions

Enhance the json schema comments

Enhance the json schema comments, specially the the JSON files in the RDBMS module #3

Cleanup README.md

Need a link to where doc is hosted and license only?

Add examples for all operations

It's fine to have a spec, but it's hard to get started from scratch when there's no example. Have to look through so many json schemas...

Document case insensitive index with unique true

@bvulaj fyi, was internal email discussion about this today. Would be good to document if / how unique case insensitive index works. I assume the index on the hidden field would just have the unique attribute set true.

CI cookbook is wrong

The query noted in the cookbook says use "option": "i" but it's actually "caseInsensitive": true

PUT: Insert New Data is wrong

• Path in example includes "/insert", it should be removed
• Example has field "entityVersion", it should be renamed to "version".
• Example has field "entity", it should be renamed to "objectType".

Create a Cookbook for new database modules

Create a Cookbook (like http://jewzaam.gitbooks.io/lightblue-user-guide/cookbook/custom_hook.html#metadata-configuration ) for new database modules ( if someone want for Cassandra, Redis, etc) (mention about PR on RDBMS modules for specific RDBMS features (example MySQL or MariDB or PostgreSQL, etc))

More on how to do binary data

Document how to create a binary field ("type": "binary" q.e.d), example is here.

Fix refernces of "returning" to be "projection"

also I think the gitbook is a bit out of date; the examples I was looking at were using "returning" instead of "projection"

Document $this and $parent

I see $this in some docs in examples but it is never explained. And $parent isn't mentioned at all.

Fix relative links with anchors

Depends on https://github.com/GitbookIO/gitbook/issues/355

Document standard metadata fields

Wondering where is best to document standard fields. Was thinking here in the user guide as a best practice.

Recommended for all data:

• creationDate: date
• createdBy: string
• lastUpdateDate: date
• lastUpdatedBy: string

For entities that are being migrated:

• migrationDate: date
• migratedFrom: string

Document permissions required for database users

For each backend, need to document permissions required to allow all operations to work.

Error in gitbook documentation

'PUT: Update Schema Status' on http://jewzaam.gitbooks.io/lightblue-user-guide/rest_specification/metadata.html is multiplied 3 times.

Add quickstart for using the java client

A simple how-to for using the client would be nice. What dependencies to include, how to setup a client instance, how to query, etc. Maybe take the examples from the existing quickstart that uses curl and do the same in java?

Add uid datatype in the documentation

This thread started in another repository ( lightblue-platform/lightblue#29 (comment) ). We have to update the documentation for UID datatype

POST: Find

• Example has "entityVersion", should be renamed to "version" I think (needs verified in spec)
• Example has "entity", should be renamed to "objectType"

Document lightblue-migrator

This is a task to document the lightblue-migrator, and also a place to drop notes on to ensure it gets documented.

Add more reference for json-schema

I thought we could add a couple more references in JSON schema article. I think we could also inform about there references right in the beginning, so the user could be aware of it. Maybe we could also add our schema into this website http://schemastore.org/ .

References:
https://spacetelescope.github.io/understanding-json-schema/
http://usingjsonschema.com/?page_id=5
http://jsonschema.net/reboot/#/ (or http://jsonschema.net/ )
http://jsonary.com/documentation/json-schema/?
https://groups.google.com/forum/#!forum/json-schema
https://stackoverflow.com/questions/tagged/jsonschema

Update audit hook documentation for identity constraints

Document that for audit hook you have to specify all the fields with an identity constraint in the hook's projection, else the hook will fail. Should include the message you'd get on such failure, to make it easier to find and fix.

Insert New Data in documentaion might be wrong

From @beachw08

In the documentation here http://docs.lightblue.io/rest_specification/data.html

The section titled Put: Insert New Data says this is how you would insert new data:
PUT /data/insert/{entityName}/{version} {request JSON document}
that doesn't work but this does:
PUT /data/{entityName}/{version} {request JSON document}

Fix broken links

There are broken links due we split the repositories. Other third party references should be also verified please.

Thanks

Add docs for all rdbms properties

The language spec for rdbms is not complete. The current language spec is a reasonable overview that hits on the more interesting bits, but there are details missing. Ideally every property available is documented, as is done in other language specifications.

Review and update docs to ensure up to date

Update docs to clarify query isn't required

"query: A non-empty query expression"

Won't be required after lightblue-platform/lightblue-core#432 is merged

Update version standard to reflect use of PATCH in all versions

Update Cookbook

http://docs.lightblue.io/cookbook/install_lightblue_on_openshift.html Need to update something in the quickstart with the list of URL's in earlier comment if they're not there already.

Add examples to rest spec docs showing what the http body looks like

Document a standard on property names in json schema

We have a mix of ways to delimit words. It makes it harder for a user to get the syntax correct if they have to remember a non-standard pattern for these things. Some examples in json schema's today:

• case_insensitive
• $path-regex
• loopCounterVariableName

Once standard is defined, open issues to fix violations where necessary.

Create a cookbook entry for case insensitive indexes

@bvulaj

lang spec data article lack of some important documentation and examples

The article http://jewzaam.gitbooks.io/lightblue-user-guide/language_specification/data.html lack how to create a update request, for example. It would be desired to have couple of examples for the requests so the reader can understand better

Document Test Harness

Should include example of overwriting datasource
See lightblue-platform/lightblue-core#463
See lightblue-platform/lightblue-core#462

Add defaultVersion to language spec / metadata

It exists in the rest spec but is missing from language spec.

Extract examples from lightblue-platform/ligthblue/docs/demo

Lots of good examples of how to do things in the demo scripts, it would be nice to extract out some of the more interesting ones into the book.

Links in REST Spec reference 404'd files

Reference files linked under http://docs.lightblue.io/rest_specification/ that lead back to github return 404s.

Mention other related projects

I could not find the mention to some other projects like lightblue-migrator or lightblue-dockerfiles and pyresttest etc. Maybe we could create new chapter about them

Better document schema statuses

They're documented in the developer guide as a key decision.

http://dev.docs.lightblue.io/key_decisions/README.html#how-will-metadata-be-versioned

This should be cleaned up and moved to the user guide. Users need to know what these things are...

Add how to use puppet

Right now is mostly in the lightblue-puppet README.md, it should move to the book. Maybe under cookbook section?

• create 'how to'/cookbook for using lightblue-puppet with hiera
• create 'how to'/cookbook for using lightblue-puppet without hiera

Put the Logical diagram picture and some description on the documentation

Put the Logical diagram picture and some description on the documentation

Cookbook: using binary (byte) data type

Add to cookbook section (new probably) how to use the byte data type. Example of storing a PDF document, since we have a real use case for it for our deployment.

Provide better/real examples

Clean metadata, sample data, and queries.
Consider using docker image(s) for setting up the examples, so it's easy to start it up and run queries with your preferred client.

Better documentation on array queries

There's nothing about elemMatch. Should note in docs that the query in the elemMatch is applied for each individual item in the array. Question came up today in looking at something with an $and in the query.