Merge pull request #105135 from diberry/diberry/0221-qna-howto-rewrite

[Cogsvcs] QnA Maker - How-to rewrite

Author: megvanhuygen

.openpublishing.redirection.json

@@ -801,34 +801,44 @@
       "redirect_url": "/azure/machine-learning",
       "redirect_document_id": false
     },
+    {
+      "source_path": "articles/cognitive-services/QnAMaker/concepts/data-sources-supported.md",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/reference-document-format-guidelines",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "articles/cognitive-services/QnAMaker/tutorials/choosing-capacity-qnamaker-deployment.md",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Concepts/azure-resources",
+      "redirect_document_id": false
+    },
     {
       "source_path": "articles/cognitive-services/QnAMaker/Quickstarts/create-publish-kb-nodejs-sdk.md",
-      "redirect_url": "/azure/cognitive-services//QnAMaker/Quickstarts/quickstart-sdk",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/quickstart-sdk",
       "redirect_document_id": false
     },
     {
       "source_path": "articles/cognitive-services/QnAMaker/Quickstarts/create-publish-kb-csharp-sdk.md",
-      "redirect_url": "/azure/cognitive-services//QnAMaker/Quickstarts/quickstart-sdk",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/quickstart-sdk",
       "redirect_document_id": false
     },
     {
       "source_path": "articles/cognitive-services/QnAMaker/Quickstarts/python-sdk.md",
-      "redirect_url": "/azure/cognitive-services//QnAMaker/Quickstarts/quickstart-sdk",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/quickstart-sdk",
       "redirect_document_id": false
     },
     {
       "source_path": "articles/cognitive-services/QnAMaker/Quickstarts/create-knowledge-rest-api-nodejs.md",
-      "redirect_url": "/azure/cognitive-services//QnAMaker/Quickstarts/publish-kb-nodejs",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/publish-kb-nodejs",
       "redirect_document_id": false
     },
     {
       "source_path": "articles/cognitive-services/QnAMaker/Quickstarts/get-answer-from-kb-using-postman.md",
-      "redirect_url": "/azure/cognitive-services//QnAMaker/Quickstarts/get-answer-from-knowledge-base-using-url-tool",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/get-answer-from-knowledge-base-using-url-tool",
       "redirect_document_id": false
     },
     {
       "source_path": "articles/cognitive-services/QnAMaker/Quickstarts/get-answer-from-kb-using-curl.md",
-      "redirect_url": "/azure/cognitive-services//QnAMaker/Quickstarts/get-answer-from-knowledge-base-using-url-tool",
+      "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/get-answer-from-knowledge-base-using-url-tool",
       "redirect_document_id": false
     },
     {
@@ -986,11 +996,6 @@
       "redirect_url": "/azure/cognitive-services/QnAMaker/quickstarts/create-new-kb-csharp",
       "redirect_document_id": false
     },
-    {
-      "source_path": "articles/cognitive-services/QnAMaker/Concepts/data-sources-supported.md",
-      "redirect_url": "/azure/cognitive-services/QnAMaker/concepts/knowledge-base",
-      "redirect_document_id": false
-    },
     {
       "source_path": "articles/cognitive-services/QnAMaker/How-To/create-knowledge-base.md",
       "redirect_url": "/azure/cognitive-services/QnAMaker/Quickstarts/create-publish-knowledge-base",

articles/cognitive-services/QnAMaker/Concepts/content-types.md

@@ -3,7 +3,7 @@ title: Content types - QnA Maker
 description: Content types include many standard structured documents such as PDF, DOC, and TXT.
 services: cognitive-services
 ms.topic: conceptual
-ms.date: 01/27/2020
+ms.date: 02/24/2020
 ---
 
 # Content types of documents you can add to a knowledge base
@@ -40,134 +40,8 @@ You can add files to a knowledge base from a public source, or your local file s
 
 ## Content format guidelines
 
-QnA Maker adds file and URL content, converting the content into QnA sets, stored as markdown (`.md`). Content is fit for a knowledge base where the content is organized in some structured form, and is represented in well-defined sections. The sections can further be broken into subsections, or subtopics. Extraction works best on content that has a clear structure with hierarchical headings.
-
-QnA Maker identifies sections and subsections and relationships in the content based on visual clues like font size, font style, numbering, colors, etc. Semi-structured content includes manuals, FAQs, guidelines, policies, brochures, flyers, and many other types of files.
-
-## FAQ URLs
-
-QnA Maker can support FAQ web pages in 3 different forms: Plain FAQ pages, FAQ pages with links, FAQ pages with a Topics Homepage.
-
-
-### Plain FAQ pages
-
-This is the most common type of FAQ page, in which the answers immediately follow the questions in the same page.
-
-Below is an example of a plain FAQ page:
-
-![Plain FAQ page example for a knowledge base](../media/qnamaker-concepts-datasources/plain-faq.png)
-
-
-### FAQ pages with links
-
-In this type of FAQ page, questions are aggregated together and are linked to answers that are either in different sections of the same page, or in different pages.
-
-Below is an example of an FAQ page with links in sections that are on the same page:
-
- ![Section Link FAQ page example for a knowledge base](../media/qnamaker-concepts-datasources/sectionlink-faq.png)
-
-
-### FAQ pages with a Topics homepage
-
-This type of FAQ has a home page with the Topics where each Topic is a link to its relevant QnAs in a different page. Here, QnA Maker crawls all the linked pages to extract the corresponding questions & answers.
-
-Below is an example of an FAQ page where a topics homepage has links to FAQ sections in different pages.
-
- ![Deep link FAQ page example for a knowledge base](../media/qnamaker-concepts-datasources/topics-faq.png)
-
-
-### Support Urls
-
-QnA Maker can process semi-structured support web pages, such as web articles that would describe how to perform a given task, how to diagnose and resolve a given problem, and what are the best practices for a given process. Extraction works best on content that has a clear structure with hierarchical headings.
-
-> [!NOTE]
-> Extraction for support articles is a new feature and is in early stages. It works best for simple pages, that are well structured, and do not contain complex headers/footers.
-
-![QnA Maker supports extraction from semi-structured web pages where a clear structure is presented with hierarchical headings](../media/qnamaker-concepts-datasources/support-web-pages-with-heirarchical-structure.png)
-
-
-## PDF/ DOC files
-
-QnA Maker can process semi-structured content in a PDF or DOC file, and convert it into QnAs. A good file that can be extracted well is one where content is organized in some structured form, and is represented in well-defined sections. The sections can further be broken inTO subsections, or subtopics. Extraction works best on documents that have a clear structure with hierarchical headings.
-
-QnA Maker identifies sections and subsections and relationships in the file based on visual clues like font size, font style, numbering, colors, etc. Semi-structured PDF or DOC files could be Manuals, FAQs, Guidelines, Policies, Brochures, Flyers, and many other types of files. Below are some example types of these files.
-
-### Product manuals
-
-A manual is typically guidance material that accompanies a product. It helps the user to set up, use, maintain, and troubleshoot the product. When QnA Maker processes a manual, it extracts the headings and subheadings as questions and the subsequent content as answers. See an example [here](https://download.microsoft.com/download/2/9/B/29B20383-302C-4517-A006-B0186F04BE28/surface-pro-4-user-guide-EN.pdf).
-
-Below is an example of a manual with an index page, and hierarchical content
-
- ![Product Manual example for a knowledge base](../media/qnamaker-concepts-datasources/product-manual.png)
-
-> [!NOTE]
-> Extraction works best on manuals that have a table of contents and/or an index page, and a clear structure with hierarchical headings.
-
-### Brochures, guidelines, papers, and other files
-
-Many other types of documents can also be processed to generate QA pairs, provided they have a clear structure and layout. These include: Brochures, guidelines, reports, white papers, scientific papers, policies, books, etc. See an example [here](https://qnamakerstore.blob.core.windows.net/qnamakerdata/docs/Manage%20Azure%20Blob%20Storage.docx).
-
-Below is an example of a semi-structured doc, without an index:
-
- ![Azure Blob storage semi-structured Doc](../media/qnamaker-concepts-datasources/semi-structured-doc.png)
-
-### Structured QnA document
-
-The format for structured Question-Answers in DOC files, is in the form of alternating Questions and Answers per line, one question per line followed by its answer in the following line, as shown below:
-
-```text
-Question1
-
-Answer1
-
-Question2
-
-Answer2
-```
-
-Below is an example of a structured QnA word document:
-
- ![Structured QnA document example for a knowledge base](../media/qnamaker-concepts-datasources/structured-qna-doc.png)
-
-## Structured *TXT*, *TSV* and *XLS* Files
-
-QnAs in the form of structured *.txt*, *.tsv* or *.xls* files can also be uploaded to QnA Maker to create or augment a knowledge base.  These can either be plain text, or can have content in RTF or HTML.
-
-| Question  | Answer  | Metadata (1 key: 1 value) |
-|-----------|---------|-------------------------|
-| Question1 | Answer1 | <code>Key1:Value1 &#124; Key2:Value2</code> |
-| Question2 | Answer2 |      `Key:Value`           |
-
-Any additional columns in the source file are ignored.
-
-### Example of structured Excel file
-
-Below is an example of a structured QnA *.xls* file, with HTML content:
-
- ![Structured QnA excel example for a knowledge base](../media/qnamaker-concepts-datasources/structured-qna-xls.png)
-
-### Example of alternate questions for single answer in Excel file
-
-Below is an example of a structured QnA *.xls* file, with several alternate questions for a single answer:
-
- ![Example of alternate questions for single answer in Excel file](../media/qnamaker-concepts-datasources/xls-alternate-question-example.png)
-
-After the file is imported, the question-and-answer pair is in the knowledge base as shown below:
-
- ![Screenshot of alternate questions for single answer imported into knowledge base](../media/qnamaker-concepts-datasources/xls-alternate-question-example-after-import.png)
-
-## Formatting considerations
-
-After importing a file or URL, QnA Maker converts and stores your content in the [markdown format](https://en.wikipedia.org/wiki/Markdown). The conversion process adds new lines in the text, such as `\n\n`. A knowledge of the markdown format helps you to understand the converted content and manage your knowledge base content.
-
-If you add or edit your content directly in your knowledge base, use **markdown formatting** to create rich text content or change the markdown format content that is already in the answer. QnA Maker supports much of the markdown format to bring rich text capabilities to your content. However, the client application, such as a chat bot may not support the same set of markdown formats. It is important to test the client application's display of answers.
-
-Learn more from the [QnA Maker markdown reference documentation](../reference-markdown-format.md).
-
-## Testing your Markdown
-
-Use the **[CommonMark](https://commonmark.org/help/tutorial/index.html)** tutorial to validate your Markdown. The tutorial has a **Try it** feature for quick copy/paste validation.
+Learn more about the [format guidelines](../reference-document-format-guidelines.md) for the different files.
 
 ## Next steps
 
-* Understand how to design and manage [question and answer (QnA) sets](question-answer-set.md)
+Understand what information is stored in a [question and answer (QnA) set](question-answer-set.md).

articles/cognitive-services/QnAMaker/How-To/add-sharepoint-datasources.md

@@ -15,7 +15,8 @@ If the QnA Maker knowledge base manager is not the Active Directory manager, you
 
 ## Prerequisites
 
-QnA Maker uses Microsoft Graph for permissions. If your SharePoint is on-premises, you won't be able to extract from SharePoint because Microsoft Graph won't be able to determine permissions.
+* Cloud-based SharePoint - QnA Maker uses Microsoft Graph for permissions. If your SharePoint is on-premises, you won't be able to extract from SharePoint because Microsoft Graph won't be able to determine permissions.
+* URL format - QnA Maker only supports SharePoint urls which are generated for sharing and are of format https://*.sharepoint.com
 
 ## Add supported file types to knowledge base
 

articles/cognitive-services/QnAMaker/How-To/business-continuity-plan.md

@@ -35,4 +35,4 @@ The high-level idea as represented above is as follows:
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Choose capacity for your QnA Maker deployment](../Tutorials/choosing-capacity-qnamaker-deployment.md)
+> [Choose capactiy](./improve-knowledge-base.md)

articles/cognitive-services/QnAMaker/How-To/get-analytics-knowledge-base.md

@@ -51,7 +51,7 @@ QnA Maker stores all chat logs and other telemetry, if you have enabled App Insi
 //Total Traffic
 requests
 | where url endswith "generateAnswer" and name startswith "POST"
-| parse kind = regex url with *"(?i)knowledgebases/"KbId"/generateAnswer" 
+| parse kind = regex url with *"(?i)knowledgebases/"KbId"/generateAnswer"
 | summarize ChatCount=count() by bin(timestamp, 1d), KbId
 ```
 
@@ -63,8 +63,8 @@ let startDate = todatetime('2019-01-01');
 let endDate = todatetime('2020-12-31');
 requests
 | where timestamp <= endDate and timestamp >=startDate
-| where url endswith "generateAnswer" and name startswith "POST" 
-| parse kind = regex url with *"(?i)knowledgebases/"KbId"/generateAnswer" 
+| where url endswith "generateAnswer" and name startswith "POST"
+| parse kind = regex url with *"(?i)knowledgebases/"KbId"/generateAnswer"
 | summarize ChatCount=count() by KbId
 ```
 
@@ -77,7 +77,7 @@ requests
 | project timestamp, id, url, resultCode, duration
 | parse kind = regex url with *"(?i)knowledgebases/"KbId"/generateAnswer"
 | join kind= inner (
-traces | extend id = operation_ParentId 
+traces | extend id = operation_ParentId
 ) on id
 | extend UserId = tostring(customDimensions['UserId'])
 | summarize ChatCount=count() by bin(timestamp, 1d), UserId, KbId
@@ -109,11 +109,11 @@ traces | extend id = operation_ParentId
 | extend answer = tostring(customDimensions['Answer'])
 | extend score = tostring(customDimensions['Score'])
 | where  score  == "0"
-| project timestamp, KbId, question, answer, score 
+| project timestamp, KbId, question, answer, score
 | order  by timestamp  desc
 ```
 
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Choose capactiy](../tutorials/choosing-capacity-qnamaker-deployment.md)
+> [Choose capactiy](./improve-knowledge-base.md)