Pattern > Overview Improvements

[sorsaffari]

@kasper-piskorski these are not all for you and this issue. after reviewing the Pattern > Overview page, I decided to take note of the topics that I realised are missing from the readme. so I'm going to include most of the text here in the doc's readme.

Nevertheless, considering that you're in charge of some of the more significant sections in the docs, I thought to share these thoughts with you in the context of the Pattern > Overview page.

The flow

The opening of the overview pages should be a complete, concise and high-level introduction to the main topic, in this case, Pattern, to provide a newbie-friendly and smoother flow. It's important that we make no assumptions about what the student may already know.

The page should always end with a summary including the links to where the user should go next.

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 to that page (sometimes also target a heading). In this case, given the strong correlation between Pattern and Query, it's important that we provide the user with a cross-reference. It's convenient for those who want to jump around the docs freely.

More headings

Every heading is turned into an anchor, which:

• 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 us and the community to leave references to specific parts of the docs when providing answers or suggestions on different platforms.

Graql instead of We

When speaking of the characteristics or capabilities of Grakn and Graql or any of their components (last sentence on this line, the subject pronoun, if used, should be within the terminology. By doing so, Grakn and Graql hold identities of their own in the mind of the developer.

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 guaranteed 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.

test-ignore

Given that you recently added the pattern test, I'm guessing we no longer need this flag. Also to clarify, we use test-ignore for code that is not testable. test-delay is used when the code is, in fact, testable but it's either not covered by the current tests, or the implemented test is failing on the code block because of a bug that is expected to be fixed in the next release.