Re-organize KG documentation for clarity and ease of understanding

[jeromechoo]

Problem

The KG documentation right now is a bit of a braindump of solutions to various support tickets and best practices. While they're individually helpful, they overwhelm new users/customers, making it challenging for them to successfully learn and integrate Diffbot KG into their system or workflow.

Purpose

To introduce new users to the minimum viable steps necessary for executing and understanding an API call that returns "data that wows" (e.g. Data that cannot be found with Google) and

Proposed Solution

First, let's establish some core principles (sorta like reddit rules) that ensures all content, regardless of who wrote it, sound like one Diffbot. This doesn't have to be perfect, we just need to have a few founding principles that we feel good about enforcing, then enforce them with all new content. Here're some:

1. Minimize Reading: Walls of copy don't inspire much learning. When writing content, remove as many words or phrases as possible that do not add value to the core topic.

2. Maximize Interaction: Practical application is incredibly memorable. Wherever possible, try to get the user to do something that provides a response. And make it easy to do so!

3. Don't Solve Problems That Don't Exist Yet: As the world's experts in the KG, we have a tendency to over-explain how it works. The KG quickstart is a great example of this. The 2nd bullet on this page explains using isCurrent to bound queries. To the fledgeling KG user reading this quickstart, this is not a problem that exists in their head yet.

   💡 As an aside, it is often better (for learning) to let users run into common problems intentionally. This DigitalOcean piece on how to implement a drop rule on iptables is a good example of having the user execute an "obvious" command, then correcting it later after explaining the repercussions.

4. Assume Cluelessness: If writing a guide, state the pre-requisites (with appropriate links). If explaining a higher level concept that makes no sense without the foundational concept, link to the foundational concept.

Feel free to add more to this list. These are just the ones that come to mind as I'm writing this.

Next, let's craft an outline to map out the KG docs:

Here's a starting outline (please rip apart if terrible). Not intended to be the outline of the sidebar. Just a high level mind map.

Diffbot Knowledge Graph
 - Introduction
   - Search vs. Enhance
   - What is DQL? (Very basic explanation)
   - Search Quickstart // links to dedicated search section below
   - Enhance Quickstart  // links to dedicated enhance section below
 - Ontology
 - Search
    - Quickstart
    - Best Practices
    - Clients & Integrations
       - Dashboard
       - Excel Add-in
       - Google Sheets Add-on
    - API Reference
 - Enhance
    - Quickstart
    - Best Practices
    - Clients & Integrations
       - Dashboard
       - Excel Add-in
       - Google Sheets Add-on
       - Zapier
    - API Reference
 - Glossary (link terms like "DQL" to this page as much as possible ala rule #4)

That's all I've got. Let me know your thoughts and what we agree on so we can divide and conquer.

[Swader]

I don't see an intro / materials for learning DQL here. Would this be covered somewhere within the quickstart and best practices of the relevant sections, or did you mean to later add a separate section dedicated just to this?

Otherwise, I agree with all of this - even the outline seems like a good choice for a sidebar.

[jeromechoo]

Good point. I think it fits right after Ontology but before Search/Enhance in the outline. The DQL specific page will be a comprehensive overview very much like what we have currently. I actually think the content in it is perfectly fine, but it needs feeder pages that don't require it to get data quickly. It's more for the user ready for advanced queries.

Diffbot Knowledge Graph
 - Introduction
   - Search vs. Enhance
   - What is DQL? (Very basic explanation)
   - Search Quickstart // links to dedicated search section below
   - Enhance Quickstart  // links to dedicated enhance section below
 - Ontology
 - Diffbot Query Language (DQL)
 - Search
    - Quickstart
    - Best Practices
    - Clients & Integrations
       - Dashboard
       - Excel Add-in
       - Google Sheets Add-on
    - API Reference
 - Enhance
    - Quickstart
    - Best Practices
    - Clients & Integrations
       - Dashboard
       - Excel Add-in
       - Google Sheets Add-on
       - Zapier
    - API Reference
 - Glossary (link terms like "DQL" to this page as much as possible ala rule #4)

[Swader]

This looks great. Is there enough content / context about the excel / sheets plugin to warrant two pages, each in a separate section?

[jeromechoo]

I'm PRETTY sure this is possible, but I planned to have one Sheets/Excel page with sections for Search and Enhance. The sidebar links will anchor link directly to the appropriate sections.

Doing so should make it pretty clear they're the same extension/add-on for both Search and Enhance.

[jeromechoo]

Also, I'm going to remove Glossary in this outline in favor of a more global glossary.

Diffbot Knowledge Graph
 - Introduction
   - Search vs. Enhance
   - What is DQL? (Very basic explanation)
   - Search Quickstart // links to dedicated search section below
   - Enhance Quickstart  // links to dedicated enhance section below
 - Ontology
 - Diffbot Query Language (DQL)
 - Search
    - Quickstart
    - Best Practices
    - Clients & Integrations
       - Dashboard
       - Excel Add-in
       - Google Sheets Add-on
    - API Reference
 - Enhance
    - Quickstart
    - Best Practices
    - Clients & Integrations
       - Dashboard
       - Excel Add-in
       - Google Sheets Add-on
       - Zapier
    - API Reference

[jeromechoo]

I'm PRETTY sure this is possible, but I planned to have one Sheets/Excel page with sections for Search and Enhance. The sidebar links will anchor link directly to the appropriate sections.

Doing so should make it pretty clear they're the same extension/add-on for both Search and Enhance.

Ugh. It doesn't work like that. Frustrating. I'll find a way around it.

[Swader]

That's why I made that link insertion script for the sidebar. It's not very customizable, so I inject stuff after docusaurus is done rendering

[jeromechoo]

I understand, but I think we can do better :). Prefer to do w/o patch fixes as much as we can.

[Swader]

Agreed, but what can we do when the toolkit is so limiting? What did you have in mind?