Integrate FAQ content into website or make searchable

[uekerman]

Problem: our search currently does not find content that is explained in FAQs. Example: "restart" should point to
https://precice.discourse.group/t/how-can-i-restart-a-coupled-simulation/675

Big solution: we (automatically) collect the complete FAQ content from Discourse and integrate into the website.

But maybe there is also a quick workaround hack?

[MakisH]

Already a very good step would be to make this more discoverable, e.g., by a link to the footer #46.

This could first lead to the Discourse tag. Later, it could lead to a dedicated page that presents links to Discourse.

[chlorenz]

I like the link in the footer as a quick fix.

There should be way to manually edit the search index, the question is what the effort is as it needs to be done on a recurring basis. Maybe we'll find a workaround, I'll look into it.

[MakisH]

There should be way to manually edit the search index, the question is what the effort is as it needs to be done on a recurring basis. Maybe we'll find a workaround, I'll look into it.

For me, this looks like a separate, lower priority issue. At least if we have an FAQ page, external search engines would index it, which is already half the effort.

I think that an returning visitor anyway notices that our search bar does not cover everything. We can improve on that, but I understand that it would be more complicated.

[fsimonis]

There is a further benefit for integrating the FAQ into the website. We can generate metadata for search engines.

[fsimonis]

The following python script assembles a json of our FAQ. Lessons learned is that the titles are not always question and the answers can be very noisy including quotes to other replies etc.
If we want to integrate this into the website, then there needs to happen a lot of post-processing from our side.

It is possible to use something like this to automatically import new FAQ entries and generate files from them in a collection. Then the workflow would be:

1. Run the importer.
2. Check if new FAQ entries were generated.
3. Manually tweak the title and text of each entry.
4. Commit the new files.

#!python3

import requests
import multiprocessing
import json
import sys

base_url = "https://precice.discourse.group"

faq_tag_endpoint = f"{base_url}/tag/faq.json"
replies_endpoint = f"{base_url}/t/{{topic_id}}/posts.json"


def get_faq_posts():
    response = requests.get(faq_tag_endpoint)
    return {
            topic["id"]: topic["title"]
            for topic in response.json()["topic_list"]["topics"]
            if topic["has_accepted_answer"]
            }


def get_accepted_answer(topic_id):
    response = requests.get(replies_endpoint.format(topic_id=topic_id))
    if not response.ok:
        print(f"Query failed with {response.reason}")
        return None
    json = response.json()
    replies = json["post_stream"]["posts"]
    for reply in replies:
        if reply["accepted_answer"]:
            return reply["cooked"]
    assert False


def fetch_post(arg):
    id, title = arg
    accepted_answer = get_accepted_answer(id)
    if accepted_answer is None:
        return None
    return {
            "question": title,
            "answer": accepted_answer
    }


# Main function
def main():
    posts = get_faq_posts()
    with multiprocessing.Pool() as pool:
        items = list(pool.map(fetch_post, posts.items()))

    json.dump(items, sys.stdout)


if __name__ == "__main__":
    main()

Notes:

• /t/{id}.json does not include all replies, so there can be cases where accepted_answer is false for all items.
• /tags.json does not include the content of the question, only the title.

[uekerman]

Maybe very naive: Does Discourse offer an option to directly embed posts? This was my original hope.

[fsimonis]

Discourse forbids embedding via iframes, that's the only easy way I found. Alternative would be to reassemble the post from the html via the API, but this may look off

[MakisH]

If we have a list of FAQ appearing on search engines, then I think this should be a shorter, targeted, curated list, and not the full list from Discourse.

I would be fine having a very short, curated list on the landing page (with the machine-readable schema), but clearly link to more on Discourse. For each question we list there, we could have a very very short answer, and link to the corresponding Discourse post for details.

[fsimonis]

I would be fine having a very short, curated list on the landing page (with the machine-readable schema), but clearly link to more on Discourse. For each question we list there, we could have a very very short answer, and link to the corresponding Discourse post for details.

This is what we would have to do. The Answer and Question schemas support text and url, so we can link both the question and the answer too.
Google says that the FAQ text must be visible on the page, where the metadata is defined.

Assuming we want to keep answers straight-forward and only refer to the topic, we could define a data as such:

- question: Can preCICE be used for volume Coupling?
  url: https://precice.discourse.group/t/can-precice-be-used-for-volume-coupling/27
  answer: Yes. Linear cell interpolation mappings offer a cost-effective alternative to rbf mappings.

[MakisH]

I like this. Then, I would suggest let's do two PRs:

• one that sets the technical mechanism
• one that populates the content

We can take care of the second during the coding days (if we have time).

[uekerman]

Discussion result:

• Create curated list with link to connected Discourse post
• Put under docs/fundamentals/FAQ
• Link from landing page and footer

[fsimonis]

Open question which influences how we store this data:

Do we want short text-only answers or use markdown in the answers?
This is allowed in the answers of the metadata:

Search displays the following HTML tags; all other tags are ignored: <h1> through <h6>, <br>, <ol>, <ul>, <li>, <a>, <p>, <div>, <b>, <strong>, <i>, and <em>.

Text only

If we go with text only, I would use a yaml data _data/faq.yaml as mentioned above.

- question: How can I handle moving meshes?
  url: https://precice.discourse.group/t/can-precice-be-used-with-moving-meshes/53
  text: Changing the mesh at runtime is not supported an being actively developed. This is often not necessary though. preCICE supports ALE-methods, direct-mesh-access, and pseudo-meshes to handle most scenarios of moving or changing meshes.

Markdown

If we want some formatting, we need collections with some naming scheme:

Example _faq/moving-meshes.md:

---
question: How can I handle moving meshes?
url: https://precice.discourse.group/t/can-precice-be-used-with-moving-meshes/53
---
Changing the mesh at runtime is not supported an being actively developed.

This is often not necessary though. preCICE supports ALE-methods, direct-mesh-access, and pseudo-meshes to handle most scenarios of moving or changing meshes.

Find more information and examples [in our documentation](couple-your-code-moving-or-changing-meshes).