typedb / typedb-docs

TypeDB Documentation

TypeDB Documentation

This repository contains all content that powers the TypeDB Documentation Portal, accessible at https://typedb.com/docs.

---

Contribute

• Read the Contribution Guidelines carefully.
• Fork this repository.
• Make the desired changes.
• Issue pull request(s) and select the base branch in accordance with the Branches section.

---

Branches

At any given time, this repository has at least two branches, i.e. master and development.

The master branch contains the content for the published documentation, available at the Documentation portal.

The development branch contains the content of the documentation to be published soon, available at the staging environment.

Main workflow is to merge changes to the development branch, test them in the staging environment, and publish to production by cherry-picking the changes to the master branch.

Hot fixes can be merged directly to the master branch, and then cherry-picked into the development branch.

---

Contribution Guidelines

Use Asciidoc syntax with Antora to write content.

• Naming Conventions
• Using Images
• Writing Style

Naming Conventions

Files and directories

• Separate words with hyphens (-).
• Keep file and directory names compact: in most cases, one or two words that best describe the contained content. Never use more than three words unless the file is a tutorial page or a Studio screenshot.
• Choosing the same name for different files located in different directories is acceptable. For example: files/social-network/schema.tql and files/phone-calls/schema.tql.
• For naming images, refer to the Images Guidelines.

Headlines

• Headlines should be phrased in a way that when read the user can determine the question that the text is meant to answer. They should describe a use-case.
• Use primitive verbs (eg: Manage Databases as opposed to Managing Databases) or Database Management.

Using Images

• The name of directories placed under images/, corresponds to the name of the section as displayed in the sidebar.
• Name of images, while remaining concise, should be to some level descriptive of their content. For example: compute_path.png and compute_path_subgraph.png as opposed to compute_0.png and compute_1.png.
• When an image is used across multiple pages, the same image file should be referenced, rather than duplicating the image.
• The source file used to generate an image is to be located under images/source/<section-name>.
• The source file must always contain the latest changes present in its corresponding image.
• Screenshots of Studio should be:
  • named after the UI/UX components of the software itself. (eg: typeql-editor_clear-query.png).
  • taken at the screen resolution of 1280 x 720 pixels.
  • of size, 1147 x 671 pixels.
  • consistent in their paddings (position of Studio's layout within the screenshot).

Writing Style

Spelling

Use American.

Headings

• There are multiple levels of headings used across all markdown files:
  • h1 (=) — page title. Only one per page at the very beginning.
  • h2 (==)
  • h3 (===)
  • h4 (====)
• Use sentence case.
• ==== always comes after a === which always comes after a ==.

Verbs and Pronouns

• With rare exceptions, the consistent tense used should be the present tense. For example: It returns as opposed to It will return.
• In most cases, the consistent pronoun is we. In special cases, you may better convey the message. Never use I.
• When speaking of the characteristics or capabilities of TypeDB and TypeQL or any of their components, the subject pronoun, if used, should be within the terminology, as opposed to we. (eg: TypeQL has three types of statements, as opposed to We have three types of statements)

Lists (Bullet points)

• Have an introductory sentence before the list, when possible. End the introductory sentence with a colon (:).
• List elements should be similar to each other as much as possible. That includes using same words, word order, punctuation, elements format, etc.
• When the list item completes the unfinished sentence before the list, end the list item with a period and start each item in lowercase.
• When the concatenation of list items construct one long sentence, end each list items with a comma or a semicolon with the last one ending with a period and start each item in lowercase.
• If the item consists of a single word, don't add end punctuation.
• If the item is a short phrase that doesn't include a verb, don't add end punctuation.
• If the item is entirely in code font, don't add end punctuation.
• If the item is entirely link text or a document title, don't add end punctuation.
• In cases other than the two described above, start the item with a capital letter and end the item with a full stop.

Serial comma

• Use serial (aka Oxford) comma.

Footer Notes and Captions

• When using a phrase, do not end the line with a period (eg: Computation of shortest path in Studio).
• When using a sentence, end the line with a period. Click on the plus icon to add a new tab..

Formulations

• Use paragraphs to provide clarity and flow.
• First sentence should describe the content of the entire paragraph at a high level.
• Avoid placing critical information in the middle or end of long paragraphs.
• Keep paragraphs short (up to 4 lines), when possible.
• Prefer short sentences to long ones. Only use complex sentence structures (multiple sentences divided by ,, ; or -), as last resort.
• Keep sentences concise. If a part of a sentence is adding no value to the point that the sentence is meant to deliver, remove it.
• Avoid the assumption that a sentence is self-explanatory. Even if explained in an earlier sentence, repeat yourself to ensure the sentence can be well-understood, without requiring reference to an earlier text.

Cross-referencing

Most of the time, when we mention something that is explained in a previous or next page, we need to leave a reference (by turning the word or phrase into a link) to that page and sometimes to a particular heading.

Flow and Headings

The choice and order of headings should provide the reader with a seamless flow that offers a high-level understanding of what that page is about. By doing this, we would also make it easier for the readers to find what they are looking for, if that is why they are visiting the page.

Every heading is turned into an anchor, which in turn:

• provides visitors with a table of content, that is essentially the summary of the page.
• enables cross-referencing one or more words to a specific block of text on the same or other pages.
• allows the community to leave references to specific parts of the docs when providing answers or suggestions on different platforms.

Keywords

All terminologies used within a page almost always need to be included as the keywords in the front matter of the markdown file. The keywords attribute contains a comma-separated list of single-word keywords and/or multiple words that are expected to be searched in combination. The longTailKeywords attribute contains a comma-separated list of keywords that form sensible combinations of the keyword items. They may also be any phrase that the user may search which relates to the page.

typedb-docs's Issues

Test for broken links in the documentation

A contributor to docs should still write links that are valid in the default MarkDown environment (therefore displayed by GitHub), but all links should be converted to HTML when Jekyll generates the HTML for dev.grakn.ai. If we can test the links before conversion (on the docs site) then we can verify every contribution PR will not contain any broken links.

Docs on how to upgrade to a new Grakn version

This issue was originally posted by @jmsfltchr on 2018-06-25 13:01.

It should be obvious to users that they may be able to update from Grakn 1.2 to 1.3 by just copying their db folder. If it works then this will save users a lot of time. Any existing docs on this should be linked to from the 1.3 release notes, which is the entry point for anyone upgrading from 1.2 to 1.3.

prism.js and prism-graql.js don't load with turbolinks inplace

This was resolved with prism's replacement - highlight.js

Expected behaviour:
when loading a page that contains snippets of graql code, the code must be highlighted.

Current behaviour:
On the initial loading of the page, the syntax highlighting is ignored and is only displayed on a reload.

Typo on the Google Cloud Deployment page

Docs version: The one currently live as of Wed, 14th of November 2018 at 12:59 (London Time)
Location of the typo: http://dev.grakn.ai/docs/cloud-deployment/gc-deployment

The typo: "Once logged in, We strongly encourage to change the default user password. In order to do so, log in to th Grakn console and type:" shoule be "Once logged in, We strongly encourage to change the default user password. In order to do so, log in to th Grakn console and type"

Add content for the Examples section

In accordance with the documentation content structure

Document how to undefine an entity

In http://dev.grakn.ai/docs/schema/concepts#undefine, there is no use case explaining how an entity can be undefined.

Finalise the first draft of the documentation content structure

The first draft of the Documentation Content Structure is not finalized. The focus on the initial structure is completeness in that the content provides full coverage of Grakn and Graql features.

Docs: design documentation architecture

This issue was originally posted by @haikalpribadi on 2018-05-21 15:32.

Automate master and development branch workflows

Once we complete #1, make 2 branches in this repo:

• master: which represents the live dev site (dev.grakn.ai).
• development: which syncs with graknlabs/grakn:master

webhooks:

• /graknlabs/grakn/release:
  • the last commit on docs is tagged with the same tag used for the grakn release
  • in docs, master is merged with development
• /graknlabs/docs/push:
  • in web-dev, the docs submodule is updated on master/development
  • if the push is made on master, in docs, development is merged with master

Docs: include the new (migration) examples

• overview
• defining the schema
• migrating csv, json and xml to the knowledge graph
• querying the knowledge graph

Automate integration test of this repo against graknlabs/grakn

Automate integration test of graknlabs/docs against graknlabs/grakn, which is triggered by a webhook in graknlabs/grakn for every commit (merged PR). This may need some work in CircleCI.

Querying with client Java: add example to docs

Add code examples in the Query section

• Graql
• Java
• Javascript
• Python

CI Workflow

We need to enable CI Workflow for @graknlabs_docs. Let's discuss what's the best way to split the "jobs" in the CI workflow in the comments below, @sorsaffari.

Add content for the Analytics section

In accordance with the documentation content structure

Improve Grakn installation instructions

Reorganisation of Tabs

Tabs (in this order):

• Linux
• Mac OS X
• Windows
• Docker

Linux should contain instructions for:

• Using RPM/Yum
• Using Debian
• Manual Download

Add missing instruction for brew-tap

For Mac installation through brew, we need to tell the users to add Grakn's brew tap

Clean up add-apt-repository command

The following command needs to be replaced a simpler and cleaner command using add-apt-repository

sudo bash <<EOF
echo "deb [ arch=all ] https://repo.grakn.ai/repository/deb/ trusty main" >> /etc/apt/sources.list.d/grakn-core.list
apt-key adv --keyserver keyserver.ubuntu.com --recv 8F3DA4B5E9AEF44C
EOF

The last line of each tab should be:

Having installed or downloaded Grakn, we can now start the [Server](#start-the-grakn-server) and interact with the [Console](/docs/running-grakn/console).

Add content for the Cloud Deployment section

In accordance with the documentation content structure

Setup the sidebar based on the revised content structure

The sidebar is to be setup based on the revised content structure

move the old content to the new structure

Add new content for the Client API section

In accordance with the documentation content structure

• Java
• Node.js
• Python

Add Readme

The readme acts as the contribution guidelines.

Remove Python and Node.js query examples

The code examples for running Graql queries using Node.js and Python clients are redundant. They need to be removed in place of a paragraph that points them to the right place in client api section. This paragraph will be presented at the top of each query page.

Use a unified universal knowledge graph for examples across different sections

Add content for the Workbase section

In accordance with the documentation content structure

Social-network example does not work with Grakn 1.5

Trying to load social-network/data.gql from development branch throws validation errors:

INVALID_ARGUMENT: InvalidKBException-A structural validation error has occurred. Please correct the [`5`] errors found. 
There is more than one thing of type [office] that owns the key [$off-1] of type [registration-number]. 
There is more than one thing of type [office] that owns the key [$off-1] of type [registration-number]. 
There is more than one thing of type [office] that owns the key [$off-1] of type [registration-number]. 
There is more than one thing of type [office] that owns the key [$off-1] of type [registration-number]. 
There is more than one thing of type [office] that owns the key [$off-1] of type [registration-number]. 

Add docs for regex property

This issue was originally posted by @haikalpribadi on 2017-02-10 15:56.

Depend on @graknlabs_graql through @graknlabs_grakn_core

As we can see below, we currently depend on @graknlabs_graql directly:
https://github.com/graknlabs/docs/blob/77db9b2110fbd51ebbd32c9fbe998fa91d1bebab/WORKSPACE#L60-L64

We've now decided that all Grakn repositories that depend on Graql should depend on @graknlabs_graql through @graknlabs_grakn_core, because:

1. simplifies the dependency-update propagation
2. we should only depend on the version of Graql that Grakn Core officially supports/implements.

This is already done in @grakn_core_client_java which we can follow in @graknlabs_docs and @graknlabs_examples:
https://github.com/graknlabs/client-java/blob/9036b5b2498e405f0a9b10d578446f2b6386b378/WORKSPACE#L36-L37

Add content for migration guidelines

Accumulate the learnings from past migration attempts to provide a set of generic guidelines on how to tackle migration of data into Grakn in the most reliable and performant way.

The guidelines should also act as the resource for answering the most frequently asked question when it comes to data migration.

Migrate graknlabs/web-dev/pages to this repository

Migrate graknlabs/web-dev/pages (what was initially in graknlabs/grakn/docs/pages) to repository, and make graknlabs/docs to be a submodule sitting inside graknlabs/web-dev/pages (needs https://github.com/graknlabs/web-dev/issues/1).

Document how to query schema concepts baed on a given type (label)

match $x type person; get $x;

Add content for the Running Grakn section

In accordance with the documentation content structure

Use proper naming for depending on grakn-core

In order to be consistent, grakn-core dependency should be named @graknlabs_grakn_core

The active status of the sidebar is not retained on page reload or redirecting link

Expected behaviour:
At any point of time, whether it's interacting with the sidebar, reloading the page or redirecting to a different page via links contained in the content, the current page must show as active in the sidebar.

Current behaviour:
Reloading the page or redirecting to a different page via a link contained in the content, removes the active state from the sidebar (all sections show as collapsed)

Add examples of using Client/Concept API in combination

Document all the use cases for information retrieval using the Client/Concept API.

At the moment, all we have to serve showcase the Client/Concept API are the quickstarts in the individual client pages. They're very basic and don't uncover the full power of the APIs.

Perhaps, we should have a series of well-crafted examples that showcase every use case our users may come across when they work with these two APIs.

Create a CI pipeline which automates testing and release

• Create a CI pipeline which updates web-dev/docs submodule when there is a new commit on docs:master

Add code examples in the schema section

Code examples are now available in Java, Node.js and Python in addition to pure Graql.

Formulate Schema Design Guidelines

We require a set of design guidelines for defining schema. These should set out the best practices for modelling a domain in Grakn for use internally and to be made available to all Grakn users. This is important, analogous to guidelines for good architecture of OOP code.

Add content for the Reasoning section

reference: #80

Update workbase docs for workbase 1.1.0

Add new content for the Concept API section

Update regex example in Graql/Concepts

emotion sub attribute datatype string regex /[like, love, funny, shocking, sad, angry]/;
to
emotion sub attribute datatype string regex /like|love|funny|shocking|sad|angry/;

Document reserved keywords

Reserved keywords

The following list Graql's reserved keywords:

Querying and query modifiers

aggregate, asc
by
compute, contains
delete, desc
from
id, in, insert
label, limit
match
offset, order
regex
get
to
val

Datatypes

datatype
boolean, double, long, string, date
true, false

Schema definition

has,
is-abstract, isa,
key,
plays,
relates

Rules definition

when, then

Statistics

Used with compute and aggregate:

count
group
max, mean, median, min
std, sum

Add meta keywords to the head of each page

Document Explanations in TypeDB's reasoner

This issue was originally posted by @kasper-piskorski on 2017-10-19 13:03.

Pages with only a few h2 headings shouldn't have table of content

Terminology Refactor

We should have an overall discussion on unified terminology for the docs, among other things:

"Grakn Java Client" vs "Grakn Client Java" vs "Java Client Grakn" etc.

Add content for the Management section

In accordance with the documentation content structure

Remaining from workbase 1.2.0 update

Description

The term Relationship Type is still present Workbase > Schema Designer > Define New Relation Type.

Relation Type in the left sidebar of Workbase > Schema Designer > Manage Attribute Types moves around when the slideshow is navigated.

Add tests for loading the social_network data

As the schema for the social_network evolves based on changes in TypeDB Core and/or type additions, the social_network's dataset may evolve as well.

For this purpose, loading the dataset into the database, needs to be tested too.

Add new content for the Query section

In accordance with the documentation content structure