{"id":21355838,"url":"https://github.com/typedb/typedb-docs","last_synced_at":"2025-04-05T15:08:46.191Z","repository":{"id":37423225,"uuid":"154169521","full_name":"typedb/typedb-docs","owner":"typedb","description":"TypeDB Documentation","archived":false,"fork":false,"pushed_at":"2024-12-18T19:37:15.000Z","size":83485,"stargazers_count":27,"open_issues_count":53,"forks_count":72,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-12-21T02:24:37.461Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typedb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-22T15:36:43.000Z","updated_at":"2024-12-18T19:37:19.000Z","dependencies_parsed_at":"2023-10-23T19:32:48.702Z","dependency_job_id":"58adc879-b7b1-4fdb-8549-734c9c87bd21","html_url":"https://github.com/typedb/typedb-docs","commit_stats":null,"previous_names":["vaticle/typedb-docs","typedb/typedb-docs","vaticle/docs"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typedb%2Ftypedb-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typedb%2Ftypedb-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typedb%2Ftypedb-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typedb%2Ftypedb-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typedb","download_url":"https://codeload.github.com/typedb/typedb-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353746,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T04:20:22.878Z","updated_at":"2025-04-05T15:08:46.174Z","avatar_url":"https://github.com/typedb.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TypeDB Documentation\n\n[![Netlify Status](https://api.netlify.com/api/v1/badges/e8d3d72a-dcb6-4e31-bfc5-deb4e665d083/deploy-status)](https://app.netlify.com/sites/typedb-docs/deploys)\n[![Discord](https://img.shields.io/discord/665254494820368395?color=7389D8\u0026label=chat\u0026logo=discord\u0026logoColor=ffffff)](https://typedb.com/discord)\n[![Discussion Forum](https://img.shields.io/badge/discourse-forum-blue.svg)](https://forum.typedb.com)\n[![Stack Overflow](https://img.shields.io/badge/stackoverflow-typedb-796de3.svg)](https://stackoverflow.com/questions/tagged/typedb)\n[![Stack Overflow](https://img.shields.io/badge/stackoverflow-typeql-3dce8c.svg)](https://stackoverflow.com/questions/tagged/typeql)\n\nThis repository contains all content that powers the TypeDB Documentation Portal, accessible at [https://typedb.com/docs](https://typedb.com/docs).\n\n---\n\n## Contribute\n\n- Read the [Contribution Guidelines](#contribution-guidelines) carefully.\n- Fork this repository.\n- Make the desired changes.\n- Issue pull request(s) and select the `base` branch in accordance with the [Branches](#branches) section.\n\n---\n\n## Branches\n\nAt any given time, this repository has at least two branches, i.e. `master` and `development`.\n\nThe `master` branch contains the content for the published documentation, available at the\n[Documentation portal](https://typedb.com/docs).\n\nThe `development` branch contains the content of the documentation to be published soon, \navailable at the [staging environment](https://development.typedb.com/docs).\n\nMain workflow is to merge changes to the `development` branch, test them in the staging environment, \nand publish to production by cherry-picking the changes to the `master` branch.\n\nHot fixes can be merged directly to the `master` branch, and then cherry-picked into the `development` branch.\n\n---\n\n## Contribution Guidelines\n\nUse Asciidoc syntax with Antora to write content.\n\n- [Naming Conventions](#naming-conventions)\n- [Using Images](#using-images)\n- [Writing Style](#writing-style)\n\n### Naming Conventions\n\n**Files and directories**\n\n- Separate words with hyphens (`-`).\n- Keep file and directory names compact: in most cases, one or two words that best describe the contained content. \n  Never use more than three words unless the file is a tutorial page or a Studio screenshot.\n- Choosing the same name for different files located in different directories is acceptable. \n  For example: `files/social-network/schema.tql` and `files/phone-calls/schema.tql`.\n- For naming images, refer to the [Images Guidelines](#using-images).\n\n**Headlines**\n\n- Headlines should be phrased in a way that when read the user can determine the question that the text is meant to \n  answer. They should describe a use-case.\n- Use primitive verbs (eg: _Manage Databases_ as opposed to _Managing Databases_) or _Database Management_.\n\n### Using Images\n\n- The name of directories placed under `images/`, corresponds to the name of the section as displayed in the sidebar.\n- Name of images, while remaining concise, should be to some level descriptive of their content.\n  For example: `compute_path.png` and `compute_path_subgraph.png` as opposed to `compute_0.png` and `compute_1.png`.\n- When an image is used across multiple pages, the **same** image file should be referenced, rather than duplicating \n  the image.\n- The source file used to generate an image is to be located under `images/source/\u003csection-name\u003e`.\n- The source file must always contain the latest changes present in its corresponding image.\n- Screenshots of Studio should be:\n  - named after the UI/UX components of the software itself. (eg: `typeql-editor_clear-query.png`).\n  - taken at the screen resolution of 1280 x 720 pixels.\n  - of size, 1147 x 671 pixels.\n  - consistent in their paddings (position of Studio's layout within the screenshot).\n\n### Writing Style\n\n**Spelling**\n\nUse American.\n\n**Headings**\n- There are multiple levels of headings used across all markdown files:\n  - h1 (`=`) — page title. Only one per page at the very beginning.\n  - h2 (`==`)\n  - h3 (`===`)\n  - h4 (`====`)\n- Use sentence case.\n- `====` always comes after a `===` which always comes after a `==`.\n\n**Verbs and Pronouns**\n\n- With rare exceptions, the consistent tense used should be the present tense. \n  For example: _It returns_ as opposed to _It will return_.\n- In most cases, the consistent pronoun is `we`. In special cases, `you` may better convey the message. Never use `I`.\n- When speaking of the characteristics or capabilities of TypeDB and TypeQL or any of their components, the subject \n  pronoun, if used, should be within the terminology, as opposed to `we`. (eg: _TypeQL_ has three types of statements, \n  as opposed to _We_ have three types of statements)\n\n**Lists (Bullet points)**\n\n- Have an introductory sentence before the list, when possible. End the introductory sentence with a colon (`:`).\n- List elements should be similar to each other as much as possible. That includes using same words, word order, \n  punctuation, elements format, etc.\n- When the list item completes the unfinished sentence before the list, end the list item with a period and start each\n  item in lowercase.\n- When the concatenation of list items construct one long sentence, end each list items with a comma or a semicolon \n  with the last one ending with a period and start each item in lowercase.\n- If the item consists of a single word, don't add end punctuation.\n- If the item is a short phrase that doesn't include a verb, don't add end punctuation.\n- If the item is entirely in code font, don't add end punctuation.\n- If the item is entirely link text or a document title, don't add end punctuation.\n- In cases other than the two described above, start the item with a capital letter and end the item with a full \n  stop.\n\n**Serial comma**\n\n- Use serial (aka Oxford) comma.\n\n**Footer Notes and Captions**\n- When using a phrase, do not end the line with a period (eg: `Computation of shortest path in Studio`).\n- When using a sentence, end the line with a period. `Click on the plus icon to add a new tab.`.\n\n**Formulations**\n- Use paragraphs to provide clarity and flow.\n- First sentence should describe the content of the entire paragraph at a high level.\n- Avoid placing critical information in the middle or end of long paragraphs.\n- Keep paragraphs short (up to 4 lines), when possible.\n- Prefer short sentences to long ones. Only use complex sentence structures (multiple sentences divided by `,`, `;` \n  or `-`), as last resort.\n- Keep sentences concise. If a part of a sentence is adding no value to the point that the sentence is meant to deliver, \n  remove it.\n- Avoid the assumption that a sentence is self-explanatory. Even if explained in an earlier sentence, repeat yourself \n  to ensure the sentence can be well-understood, without requiring reference to an earlier text.\n\n### Cross-referencing\nMost of the time, when we mention something that is explained in a previous or next page, we need to leave a reference \n(by turning the word or phrase into a link) to that page and sometimes to a particular heading.\n\n### Flow and Headings\nThe choice and order of headings should provide the reader with a seamless flow that offers a high-level understanding \nof what that page is about. By doing this, we would also make it easier for the readers to find what they are looking \nfor, if that is why they are visiting the page.\n\nEvery heading is turned into an anchor, which in turn:\n- provides visitors with a table of content, that is essentially the summary of the page.\n- enables cross-referencing one or more words to a specific block of text on the same or other pages.\n- allows the community to leave references to specific parts of the docs when providing answers or suggestions on \n  different platforms.\n\n### Keywords\nAll terminologies used within a page almost always need to be included as the keywords in the front matter of the \nmarkdown file.\nThe `keywords` attribute contains a comma-separated list of single-word keywords and/or multiple words that are \nexpected to be searched in combination.\nThe `longTailKeywords` attribute contains a comma-separated list of keywords that form sensible combinations of the \nkeyword items. They may also be any phrase that the user may search which relates to the page.\n\n\u003c!-- **TypeDB Terminology**\n\n**Common Terms** --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypedb%2Ftypedb-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypedb%2Ftypedb-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypedb%2Ftypedb-docs/lists"}